Notification of event handlers in broadcast or propagation mode by event management services in a computer system

ABSTRACT

A computer operating system manages events of interest to a plurality of event handlers within respective programs. The event handlers are arranged in a sequence for the purpose of receiving sequential notification of an occurrence of the event. When the event occurs, the first event handler in the sequence is notified, and it then handles the event. Then, the first event handler determines if the second event handler in the sequence should be notified of the event. If so, the second event handler in the sequence receives the event notification, handles the event, and then determines if the third event handler in the sequence should be notified. In this manner, the event notification can be propagated from event handler to event handler in the sequence, but any event handler in the sequence which receives the notification can block subsequent propagation of the event notification. This technique saves processing time in situations where some or all of the event handlers in the sequence (after the first event handler) may not benefit from the event notification; in such a case, the event notification is not propagated to them.

This is a continuation of application Ser. No. 07/744,850 filed on Aug.12, 1991, U.S. Pat. No. 5,305,454.

BACKGROUND OF THE INVENTION

The invention relates generally to computer operating systems, and dealsmore particularly with event management services within a computeroperating system.

During the course of operating a computer system, many types of eventscan occur, for example, pressing of an enter (function) key on akeyboard, loading of data from a disk into memory, or occurrence ofsevere errors or trace events, etc. Data may be associated with theevent such as a character key that was pressed before the enter key orthe name of the disk that was loaded. Previously known operating systemsmanage events such that when the event occurs, the operating systemsnotify one or more application programs executing within the system thatare interested in the event and furnish associated event data, if any.After notification, the application program or programs can process theevent data, or take other action in response to the event notification.

A prior art IBM System/38 operating system manages events in thefollowing manner. Each of the events is defined with a name from apredetermined set of numerical names, consisting of a class, type andsubtype. The operating system reserves certain of the predeterminednames to represent common hardware and software events, and makes theother names available to application programs to identify other events.Application programs also can dynamically define event monitors toreceive notification of defined events. When the event occurs, theoperating system or the application that detects the event calls anEventSignal function, and then continues with other processing. TheEventSignal function signals one or more of the event monitors which areinterested in the event, i.e. all of the event monitors which nameevents having the same class, type, and subtype identification as foundin the event definition. Generic type and/or subtype specifications arealso allowed. If there is more than one interested event monitor, theEventSignal function signals the interested event monitors in abroadcast mode, i.e. substantially simultaneously. Then, the eventmonitor(s) notify respective event handling subroutines of applicationprogram(s) which are interested in the event, to act upon the eventnotification and/or-process the event-data.

The event handlers operate synchronously or asynchronously relative tothe occurrence of the events. In an asynchronous "trap" mode, the eventhandler requests notification of an event but does not wait idly for theevent to occur if it has not yet occurred. When the event occurs and therespective event monitor is signalled, the event monitor notifies theevent handler by sending an interrupt followed by the event data. In asynchronous "test" mode, the event handler periodically asks the eventmonitor whether the event has occurred, and if so, responds to the eventand/or processes event data. If the event has not occurred, then theevent handler performs other work. In a synchronous "trap" mode, theevent handler requests the event notification and event data once, waitsin a sleep mode until the event occurs; and is awakened with the eventnotification. The System/38 operating system also supports dynamicenabling and disabling of event monitors. A disabled event monitor willnot notify the corresponding event handler of an event. Also, in theSystem/38 operating system, it is possible to mask an event handleragainst receipt of event signals.

Certain types of events such as program trace events are generatedperiodically. The System/38 operating system allows specification of amaximum number of events and associated event data to be retained, tiedto an interested event monitor, or specification that the events andassociated event data should be retained without limit while aninterested event monitor is disabled. In the former case, when themaximum number of events and associated event data is exceeded,subsequent new events and associated event data which exceed the maximumlevel are discarded.

While the System/38 operating system provides a substantial amount ofcontrol and efficiency in managing events and permits associatedapplication programs to participate in defining the event managementservices, further improvements are desirable to permit an operatingsystem to more efficiently and more comprehensively manage the eventsaccording to the specific requirements of the computer system and theassociated application programs.

Accordingly, a general object of the present invention is to provideevent management services which efficiently and comprehensively manageevents and permit associated application programs and other parts of thecomputer system to tailor the event management services to theirspecific needs.

Another object of the present invention is to provide event managementservices of the foregoing type which permit associated event signallers,event definers and/or event handlers to operate in an efficient andoptimum manner.

SUMMARY OF THE INVENTION

The invention-resides in a computer operating system which managesevents of interest to a plurality of event handlers within respectiveprograms. The event handlers are arranged in a sequence for the purposeof receiving sequential notification of an occurrence of the event. Whenthe event occurs, the first event handler in the sequence is notified,and it then handles the event. Then, the first event handler determinesif the second event handler in the sequence should be notified of theevent. If so, the second event handler in the sequence receives theevent notification, handles the event, and then determines if the thirdevent handler in the sequence should be notified. In this manner, theevent notification can be propagated from event handler to event handlerin the sequence, but any event handler in the sequence which receivesthe notification can block subsequent propagation of the eventnotification. This technique saves processing time in situations wheresome or all of the event handlers in the sequence (after the first eventhandler) may not benefit from the event notification; in such a case,the event notification is not propagated to them. For example, if thefunction of the first event handler is to analyze the severity of afailure, and the function of the second event handler is to recover fromthe failure, if the failure is so severe that recovery is not possible,then the first event handler should not allow notification to the secondevent handler. To do so, would merely waste processor time.

According to one feature of the invention, the operating system permitsselection of the mode of notifying a plurality of event handlers whichare all interested in the event, the foregoing propagation mode or abroadcast mode in which all interested event handlers receive the eventnotification simultaneously or at least without any contingencies. Aprogram specifies the mode of notifying the interested event handlers byfurnishing a corresponding parameter for a definition of the event. Whenthe event occurs, an event manager within the operating system reads theevent definition to determine the mode of notifying the interested eventhandlers. A program can specify interest in a combination of events ofthe same or different types and if the propagation mode is selected,each event handler in a sequence which receives notification of an eventcan decide to propagate any number or none of the event signals ofinterest.

BRIEF DESCRIPTION OF THE FIGURES

FIG. 1 is block diagram illustrating key components of an operatingsystem providing event management services according to the presentinvention, and associated application program threads and hardware.

FIGS. 2 (a-c) form a flowchart illustrating operation of the operatingsystem of FIG. 1 when an event occurs and an interested applicationprogram thread, while in a wait mode, is notified of the event.

FIG. 3 is a flowchart illustrating an EventDiscard function of theoperating system of FIG. 1.

FIG. 4 is a flowchart illustrating an EventMonitorReset function of theoperating system of FIG. 1.

FIG. 5 is a flowchart illustrating operation of the operating system ofFIG. 1 when an event occurs and an interested application programthread, while in a test mode, is notified of the event.

FIGS. 6 (a-b) form a flowchart illustrating operation of the operatingsystem of FIG. 1 when an event occurs and an interested applicationprogram thread, while in a trap mode, is notified of the event.

FIG. 7 is a flowchart illustrating a broadcast mode of signalling twoevent monitors which are interested in the same event.

FIG. 8 is flowchart illustrating a propagation mode of signalling twoevent monitors which are interested in the same event.

FIG. 9 is a block diagram illustrating chaining of two event monitorswithin the operating system of FIG. 1, which event monitors are bothinterested in the same event.

FIG. 10 is a block diagram illustrating chaining of five event monitorswithin the operating system of FIG. 1, which event monitors areinterested in different sets of events.

FIG. 11 is a flowchart illustrating an EventDelete function of theoperating system of FIG. 1.

FIG. 12 is a flowchart illustrating an EventEnable function of theoperating system of FIG. 1.

FIG. 13 is a flowchart illustrating an EventMonitorEnable function ofthe operating system of FIG. 1.

FIG. 14 is a flowchart illustrating an EventSelect function of theoperating system of FIG. 1.

FIG. 15 is a flowchart illustrating an EventMonitorSelect function ofthe operating system of FIG. 1.

FIG. 16 is a flowchart illustrating an EventMonitorDelete function ofthe operating system of FIG. 1.

FIG. 17 is a flowchart illustrating an EventMonitorCreate function ofthe operating system of FIG. 1.

FIG. 18 and FIG. 19 are flowcharts illustrating the trace managementservices of the operating system of FIG. 1.

DETAILED DESCRIPTION OF THE PREFERRED EMBODIMENTS

Referring now to the drawings in detail wherein like reference numeralsindicate like elements throughout the several views, FIG. 1 illustratesanevent management services portion of a multitasking operating systemgenerally designated 11 according to the present invention. Theoperating system 11 is preferably programmed in executable form onto acomputer readable medium such as a magnetic disk or tape, loaded intothe computer memory 21 and executed on a CPU 19. However, the operatingsystem 11 or part thereof could also be implemented by equivalenthardware.

Operating system 11 and associated application programs provide manyfunctions which are described in more detail below. The functions can begrouped into the following categories: event defining, event signalling,event monitor creating, event monitoring, event monitor processing andevent handling.

An event definition includes an event name to identify the event andattributes of the event to control some operating system responses tothe event. The operating system only recognizes the defined events.

The operating system or application program signals an event tocommunicatethe occurrence of the event. The event signal is alwaysassociated with theprocess which signals the event. An event can bedefined so that its signalis recognized only within this process or elsethroughout the entire session containing this process. The event signalcan include data associated with the event and a key which specifiesparticular occurrencesof the event or a subset of types of event datasuch as the source of the data.

If an application program or other function within the operating system11 is interested in receiving notification of an event and the eventdata, ifany, the application program or other operating system functiondefines an event monitor. The definition specifies one or a combinationof events, ofthe same or different type, of interest to the eventmonitor. In the embodiment of the present invention described herein indetail, if more than one occurrence of the same type of event isrequired to satisfy the event monitor, then the event type is listedmore than once in the event monitor definition. (Alternately, each eventtype can be listed just once in the event monitor definition, and acount provided for each event type to indicate the minimum number ofevents of that type required to satisfy the event monitor.) Thedefinition can also specify a key with each event name to limit theevent occurrences of interest to the event monitor. The event monitorcan monitor event signals provided by other program threads within thesame process or signals of events which have been defined with sessionscope. The event monitor definition also specifies the number or "count"of distinct event signals, i.e. the number of the specified eventswhichmust have occurred at least once, which are required to "satisfy"theevent monitor. Only when the event monitor is satisfied will theevent monitor give the associated event handler access to stored eventsignals. To provide such access, the event handler makes a request tothe event monitor, and if the event monitor is satisfied, the eventmonitor will notify the event handler that the event monitor issatisfied and the location of the stored event signals. This request cantake the form of anEventTrap, EventWait or EventTest call. Afterreceiving notification that the event monitor is satisfied, the eventhandler can retrieve and processthe event data. The manner ofinterpreting the event data is based on a private protocol between theevent signaller and event handler, and is established separately foreach named event. The event management serviceswithin operating system11 provides a channel for delivering the event notification and eventdata to the event handler. After the event handler retrieves andprocesses the event data, the event monitor must be reset before theevent handler can retrieve and process new event signals.

The event management services within operating system 11 comprise eventdefiners 12a,b, resultant event definitions 16a-d, event monitors 28a-d,event signallers 18a,b, and an event signal manager 26. Although notshown, the operating system 11 could also include event monitor definersand event handlers. FIG. 1 also illustrates event definers 13a,b, eventsignallers 15a,b, event monitor definers 17a-d, and event handlers14a-d, within respective application program threads that run onoperating system11. While each of the foregoing application programthreads 13a-d, 14a-d, 15a,b and 17a-d may be a member of a differentcomputer process, typicallyeach pair of event monitor definers and eventhandlers (17a, 14a), (17b, 14b), (17c, 14c) and (17d, 14d) is part ofthe same process, and either each pair of event definers and eventsignallers is part of the same process or resides within operatingsystem 11, or the event definer is within the operating system and theevent signaller is outside the operating system as an applicationprogram.

The following is a high level description of the operation of operatingsystem 11 and associated application program threads. The eventsignallers18a,b and 15a,b detect the occurrence of events, and signalthe event signal manager 26 with an indication of the occurrence of theevent, the event name, event key (i.e. subset of types of event dataaccompanying theevent) and specific event data. In response, the eventsignal manager compares the name of the signalled event to those in theevent definitions16-d to determine if the named event has been definedand, if so, to read attributes of the event. The attributes indicatewhether the event signaller must be required to wait for the event to behandled before proceeding with other work or whether the event signallermust be permitted to proceed with other work during event handling, amaximum number of event signals that can be stored if there arecurrently no eventmonitors which are interested in the event, and abroadcast or propagation mode for notifying multiple event monitorswhich are interested in the event. Based on the first attribute, theevent signal manager either causes the event signaller to wait for eventhandling to be completed or permits it to continue processing beforeevent handling is completed. The event signal manager also reviews thedefinitions of event monitors 28a-d to determine if one or more eventmonitors have been defined which reference, i.e. are interested in, thenamed event with limiting event key. If not, the event signal managerstores the event signal, tied to theevent definition, in accordance withthe second attribute of the event definition. However, if at least oneevent monitor is interested in the named event with limiting event key,the event signal manager signals the event monitor with the eventnotification and event data. If there are twoor more interested eventmonitors, then the event signal manager signals the interested eventmonitors in the broadcast or propagation mode as specified in the eventdefinition. The event monitor definition indicates the maximum number ofsignals of each listed event that can be stored bound to the eventmonitor for subsequent transmission to the interested event handler, andthe number of distinct event signals required to "satisfy" the eventmonitor. If satisfied, each signalled event monitor iseligible to notifythe respective event handler of the event upon request by the eventhandler in the requested manner, i.e. wait, trap or test mode. The eventhandlers respond to the event notification and/or process the eventdata, if any.

The following is a more detailed description of the present invention.The operating system can define events such as process creation, processdeletion, begin command, end command, command not found, reset, programload, program unload, console output complete, console input available,error, timer, trace, I/O and accounting events. An error event is, forexample, a program check, a severed connection or other system failure.A timer event is the end of a timing period. A trace event is thecompletionof a program subroutine, thread or significant step of aprogram (for example, accessing data, sending data, dispatching a newthread, suspending a thread, etc). An accounting event is use of thecomputer system which may result in a charge to the user. Theapplication programs can define any type of event such as the completionof a function, a checkpoint in the function, data creation, datadeletion, application program error events (ex. a user entry error) or arequest for responsive action. For example, if the application programwants to control a roboticarm, the application program can define anevent which is a request to movethe arm, and subsequently signal theevent, i.e. the request, and provide event data to define how much andin what direction to move the arm. The operating system or theapplication programs can define the events at any time, i.e. duringsession initialization, at first invocation of a servicethat detects theevent, or at any other time. Each event is defined by calling anEventCreate function 40 within event signal manager 26 and specifyingdefinition parameters. The call for this function and each otherfunction within event signal manager 26 is described in detail in asection entitled "Event Signal Manager Function Calls" below.

Based on the parameters in the call, each event definition 16a-dincludes an event name and important attributes or characteristics ofthe event. Each event name is a character string having a length andcomposition determined by the event definer, and provides the primaryidentification of the event. The attributes include scope of the eventname, loose signallimit, mode of signalling the interested eventmonitor(s) 28a-d, and operational status of the respective eventsignaller 15a,b or 18a,b duringthe event notification and processing.The event definition also includes enable and select fields as describedbelow with reference to FIG. 12 and 14. Also, as described in moredetail below with reference to FIG. 2a-c, the event signaller calls anEventSignal function 49 within the event signal manager which reads theattributes of the named event to determine in part how to manage theevent.

The scope of the event name attribute indicates either a single processor an entire session in which the event name has significance. If anevent name has process scope only, then only the process which definedthe eventmay signal the event and only those event monitors defined inthat process which reference the event name can be signalled by theEventSignal function. However, if an event name has session wide scope,then all eventmonitors that reference the event name can be signalled bythe EventSignal function after receiving the event signal regardless ofwhat process signalled the event. Each event name having session widescope must be unique within the system; however, each event name havingprocess scope need only be unique within the process that signals andmonitors the event.

The loose signal limit attribute is the number of events and associatedevent data ("loose signals" 41) that are stored at the direction of theEventSignal function in association with the corresponding eventdefinition after the event is defined and the event occurs, but in theabsence of any event monitors that are currently interested in theevent. After the loose signal limit of event signals is reached, eachsubsequent event signal is stored at the expense of the oldest eventsignal which is then erased. The storage of loose signals is importantbecause an event monitor may be defined later which is interested in theevent and benefit from the previous event signals.

The mode of signalling attribute refers to the manner of signalling morethan one event monitor that is interested in the same event. In abroadcast mode, the EventSignal function signals all interested eventmonitors without contingency, usually at substantially the same time.The event definition should indicate the broadcast mode when all of theinterested event monitors can benefit from the event notification andevent data regardless of the nature of the event. For example, if theevent is the loading of data from a disk into memory and there aremultiple event handlers which are interested in reading the data, thenit is most efficient to broadcast the event notification and event datato the event handlers (via the associated event monitors) soon after theoccurrence of the event and without any contingency so that those eventhandlers may be dispatched by the operating system for optionalconcurrency. In a FIFO propagation mode, the event monitors are subjecttonotification in order of creation of the event monitors, and in a LIFOpropagation mode, the event monitors are subject to notification inreverse order of creation of the event monitors. The event handlerassociated with each event monitor that is signalled controls whetherthe next event monitor in the sequence is signalled as to the occurrenceof the event. To do this, each event handler that receives the eventsignal calls an EventMonitorReset function to permit propagation ofspecified event signals in the current signal set to the next eventmonitor in the sequence. Each event handler in the sequence can alsocall an EventDiscardfunction to prevent propagation of one or more eventsignals to the next (and all downstream) event monitors in the sequence.Event signal propagation rules are applied on a process basis; wheninterested event handlers reside in different processes, the eventsignal is always delivered to at least one event monitor in each of theprocesses. This control is described in more detail below with referenceto FIGS. 7 and 8,and permits each event handler in the sequence to avoidprocessing of the event data by subsequent event handlers in thesequence when the event handler determines that the system will notbenefit by propagation of the event signal. For example, assume that theevent is a severe failure, a function of the first event handler in thesequence is to analyze the nature of the failure, and a function of thenext event handler in the sequence is to recover from the failure. Ifthe failure is so severe that recovery is not possible, then the firstevent handler should block the propagation of the event signal to thenext event handler in the sequence.Thus, the effect of the blocking isto improve the overall efficiency of the system.

The operational status attribute within the event definition refers tothe synchronous or asynchronous treatment of the process which signalsthe event while the EventSignal function signals the event monitor, theevent monitor notifies the event handler, and the event handler actsupon the event and processes the event data. For example, if the eventis an error in the process that signalled the event, then it may bepreferable to suspend the process that signalled the event (synchronoustreatment) the error is recovered by the interested event handler.However, if the event represents normal operation of the event signallerand the event signallershould be ready to process other similar events(asynchronous treatment), such as the pressing of a keyboard functionkey, then the event signaller process should not be suspended while theevent monitor is signalled and notifies the event handler and the eventhandler processes the event data.If the event represents a "call" to anexit routine, then the process whichsignalled or called the exit routineshould be suspended until the event ishandled, and the event attributeshould indicate the synchronous treatment.An exit routine is a block ofcode which is usually provided by a user of operating system 11 toperform a user-specific or installation-specific function. Suchfunctions can be optional, additional or otherwise externalto theoperation of the product. If no event monitor for the exit routine eventhas been defined, then the calling program continues to execute andthere is no system failure. Also, the exit routine can reside in adifferent process from the caller to shield the resources of the callingprocess from the exit routine. The event handler can provide an exitroutine, in which case control typically should not return to the calleruntil the exit routine is executed; therefore, the exit routine shouldbe defined as an event with the synchronous attribute.

The event monitor definers 17a-d (or other event monitor definers notshown, within operating system 11) define the event monitors 28a-drespectively by calling an EventMonitorCreate function 42 and specifyingthe event monitor parameters. Each call identifies one or more eventnames, respective event keys, the number of occurrences of distincteventsto satisfy the event monitor, and a bound signal limit for eachevent and other attributes of the event monitor. The key may be a"wildcard" indicating that the event monitor is interested in all typesof the named event, or may be a subset of the types of named events. Theevent monitor definition also includes enable, select, delete, wait andtrap fields described below. As described above, after receiving thename of the eventand event key from the event signaller and verifyingthat the named event has been defined, the EventSignal function readsthe event monitor definitions to determine which one or ones, if any,recite the event name and key. If one or more such event monitors havebeen defined, then the EventSignal function calls them in the broadcastor propagation mode as specified in the event definition.

The use of the keys simplifies the definitions of the events which canlista general event name such as the pressing of an enter key or theloading ofa disk into memory, while the event monitor definition limitsthe event signalling to the event monitor based on the key within theevent monitor definition. For example, the event monitor key may belimited to a specific set of character keys or type of loaded disk.

The next attribute listed above in the event monitor definition, thenumberor count of distinct event signals required to satisfy the eventmonitor, causes the event monitor to withhold notification of the eventsignals to the associated event handler until after the specified numberof distinct events named in the event monitor definition have occurred.For example, art event handler which has the function of recoveringcommunication errors may be interested in receiving notification of theerrors only whena total of ten communication facility errors and/orparity errors have occurred in order to justify further analysis; alesser number of the errors may not be deemed significant enough toinitiate recovery. In this embodiment of the present invention, if thecommunication error is listed ten times and the parity error is listedten times and the count is specified as ten, the breakdown between thenumber of errors of each specified type is not critical to thesatisfaction of the event monitor aslong as a total of ten occurrencesof either or both types have occurred. However, if the communicationerror is listed five times and the parity error is listed five times andthe count is ten, then five of each type ofevent must occur to satisfythe event monitor. Thus, the event monitor definer can specify aparticular number of occurrences of each event type of interest requiredto satisfy the event monitor.

The last attribute listed above in the event monitor definition, thebound signal limit, is the number of unprocessed event signals that canbe stored at the direction of the interested event monitor, bound to orassociated with each designated event in the interested event monitor.When the limit is exceeded, the oldest bound event signal is erased, andthe newest event signal is bound to the event monitor. For example, abound signal limit for the storage of a fixed number of trace events anddata is useful to assist in trouble shooting an event condition, whereasadditional, older trace data may not be useful because it may notreflect current problems. The bound signals are stored in a bound signalset 47. When an event monitor is satisfied and an event handler requestsevent notification, the event monitor designates the oldest bounddistinct eventsignals as a current signal set 45 for access by the eventhandler. If morethan one occurrence of the same type of event isrequired to satisfy the event monitor, then the current signal setincludes at least the number ofevent signals for the type as required tosatisfy the event monitor.

Another attribute in the event monitor definition specifies whether ornot the event monitor, when created, should receive signals of the typeor types in which the event monitor is interested but which occurredbefore creation of the event monitor and are stored in the loose signalset. If so, the loose signals are transferred to the bound signal set 47upon creation of the event monitor. Still another attribute in the eventmonitor definition specifies whether or not other program threads withinthe same process as the event handler should be suspended after theevent monitor is satisfied and while the event handler receives theevent notification and handles the event. It may be important to suspendexecution of the other program threads if the event is a system failurewhich requires an abend or an event which requires the event handler totake a "snapshot" of the entire process.

As noted above, typically each event monitor definer and associatedevent handler are part of the same process so that when a process wantsto monitor an event or combination of events and handle the event orcombination, the process defines the event monitor and provides anassociated event handler that is notified pursuant to a call by theevent handler to the EventTest, EventTrap or EventWait function. Theprocess candefine or delete the event monitor and involve the eventhandler dynamically, i.e. at any time without relinking or interruptingother programs, by calling the EventMonitorCreate or EventMonitorDeletefunctionand the EventTest, EventTrap or EventWait function. Also,multiple processes can,define multiple event monitors and providemultiple event handlers for the same or different events or combinationsof events.

After receiving the call, the EventMonitorCreate function reads andstores all the parameters in the call (step 80 of FIG. 17). Next, theEventMonitorCreate function determines if an event monitor flagparameter indicates that loose signals should be bound (decision block82). If so, the EventMonitorCreate function reads the loose signal setassociated withthe definition of each event of interest to the eventmonitor to determine if there are loose signals with limiting key("qualified events") of interest to the event monitor. To be of interestto the event monitor, theloose signals must either have session scope orhave process scope with theevent being defined by the same process thatdefined the event monitor. If there were no prior occurrences of theevent or if another event monitor was previously defined to haveinterest in the event, then there will be no loose signals. If there areloose signals of interest, the EventMonitorCreate function transfers allthese loose signals to the eventmonitor (step 86), and the event monitorbinds them to itself in accordancewith its bound limits as describedbelow with reference to step 115 of FIG.2. Then, the EventMonitorCreatefunction returns to its caller (step 88).

At any time after an event monitor definer 17a-d defines an eventmonitor, the associated event handler can request notification when theevent monitor is satisfied. The types of requests include test, trap andwait modes, and the event handler selects the desired mode with a callto an EventTest function 50, EventTrap function 52, or EventWaitfunction 54. The effect of each call depends of the state of therespective event monitor.

If the event monitor is not yet satisfied, then the following occurs:

1) The EventTest function, if called by the event handler, reports tothe event handler the state of each event name-event key pair(referenced in the event monitor associated with the event handler),i.e. whether the named event with appropriate key has occurred or beendeleted.

2) The EventWait function, if called by the event handler, suspends theevent handler until the event monitor is satisfied. When satisfied, theevent monitor awakens the event handler and reports the state of each ofthe event name-event key pairs.

3) The EventTrap function, if called by the event handler, informs theoperating system that a trap routine should be run when the eventmonitor is satisfied. Because the operating system does not know in whatenvironment the trap routine will run, no information regarding thecondition of the event monitor is initially passed to the trap routine.Therefore, when the event monitor is satisfied, the event monitorinvokes the trap routine and the trap routine calls the EventTestfunction to obtain a report on the state of each event name-event keypair. If at the time the event monitor is-satisfied, both an EventTrapand EventWait function have been called, the EventWait function takesprecedence and thetrap routine is not run.

If the event monitor is satisfied, but is not yet activated (i.e. notyet asked by an event handler for event notification), then thefollowing occurs:

1) The EventTest function, if called by the event handler, activates theevent monitor and causes the event monitor to establish the currentsignalset and report to the event handler the state of each eventname-event key pair.

2) The EventWait function, if called by the event handler, activates theevent monitor and causes the event monitor to establish the currentsignalset, awaken the event handler and report the state of each eventname-eventkey pair.

3) The EventTrap function, if called by the event handler, causes theeventmonitor to establish the current signal set and run the specifiedtrap routine.

An event monitor is "active" (after the event monitor is satisfied andan event handler has requested event notification) while the eventhandling program is executing as a result of a call to the EventWaitfunction, EventTrap function or EventTest function. If the event monitoris currently active, then the following occurs:

1) The EventTest function, if called by the event handler, reports tothe event handler the state of each event name-event key pair.

2) The EventWait function, if called by the event handler, resets theeventmonitor and suspends the event handler until the event monitor isagain satisfied.

3) The EventTrap function, if called by the event handler, lists withthe event monitor the address of the trap routine, overwriting theaddress of any trap routine previously associated with this eventmonitor.

When an event monitor is active, new event signals which it monitors arestill bound to the event monitor and are processed by the event monitorafter the EventMonitorReset function 62 is executed. Then, the eventmonitor examines the remaining bound signals, and if they are sufficientto satisfy the event monitor, the event monitor is again eligible foractivation.

FIG. 2 is a flowchart illustrating operation of operating system 11,particularly the EventSignal function 9, event monitor 28a and eventhandler 14a, when the event handler calls the EventWait function 54.During step 90, the event definer 12a within the operating systemdefines an Event A (with session scope) although event definer 13awithin an application program could just as well have defined Event A.For example, Event A is the pressing of an enter key on a keyboardfollowing the pressing of a character key. Concurrently or at a latertime, event monitor definer 17a within an application program defines anevent monitor28a which is interested in Event A by calling theEventMonitorCreate function (step 92). Later, event handler 14a callsthe EventWait function 54 to indicate that the event handler willsynchronously wait for event monitor 28a to be signalled of an event,and informs the EventWait function where the event data should be stored(step 94). In response to the call, the EventWait function sets a waitbit in event monitor 28a, lists the caller (event handler 14a) with theevent monitor 28a (step 95),and renders the event handler in a sleepmode whereby it waits for the event notification without performing anyother operations (step 94). At alater time, a person presses thecharacter key and then the enter key, and a subroutine (event signaller18a) which continually monitors the keyboarddetects the pressing of thekeys. In response, event signaller 18a the EventSignal function 49 andprovides the event name, limiting key, if any,and event data (step 100).The EventSignal function 49 reads the event definitions 16a-d todetermine if Event A has been defined in the same process as thesignaller or with session scope (step 102 and decision block 104). Ifnot, the EventSignal function returns an error code to the eventsignaller (step 105). However, in the illustrated example, Event A hasbeen defined with session scope, and the EventSignal function notesindecision block 106 that the event definition is selected-on (asdescribed below with reference to FIG. 14). Then, the EventSignalfunction decides, based on the event definition attribute, whether ornot the event signaller should be stopped (synchronous treatment) untilthe event is handled (decision block 107), and if so, causes the eventsignaller to stop (step 108). In either case, the EventSignal functionnext reads the event monitor definitions 28a-d to determine if any eventmonitors are interested in Event A and whatever limiting key, if any,limits the interest of the event monitor (step 109 and decision block110). If no event monitor is interested in the event and limiting key,the EventSignalfunction binds the signal to the event definition inaccordance with the loose signal limit (step 111). If the loose signallimit has already been attained, then the oldest loose signal isdiscarded. If there are one or more event monitors which are interestedin the event name with limiting key and are selected-on (decision block112), the EventSignal function provides the event signal (event name andevent data) to all of them nearly simultaneously if the event definitionspecifies the broadcast modeattribute (step 114a), or to the first eventmonitor in the sequence if theevent definition specifies the propagationmode attribute (step 114b). In the illustrated example, there is onlyone event monitor which is interested in the named event with limitingkey and is selected-on. However, if all event monitors that wereinterested in the event with limiting key were selected-off, then theevent monitors would not be notified and the event signals would bebound to the event definition in loose signal set 41 (step 111). Thesignalled event monitor 28a binds the event signal to itself by storingthe event signal in bound signal set 47.Next, the event monitordetermines if it is satisfied by comparing the number of distinct eventsignals stored in the bound signal set 47 to an "event₋₋ count" field inthe event monitor definition (step 116). Thenumber of distinct signalsof events of interest to the event monitor indicated by the event countmust occur in order to satisfy the event monitor. As previously noted,one type of event can be listed more than once in the event monitordefinition. In the alternate embodiment of the invention describedabove, in step 116, the event monitor determines if the specified numberof occurrences of each event type have occurred to satisfy the eventmonitor. If the event monitor is not yet satisfied, no further action istaken by the event monitor or the associated event handler as a resultof this occurrence of Event A. However, if the event monitor issatisfied, then the event monitor proceeds to determine if there is anEventWait call outstanding by reading the wait bit (decision block 117).In this example, the wait bit was set in step 95, and the event monitorthen proceeds to establish a current signal set 45 by designating fromthe bound signal set 47 all distinct signals (step. 118),and awakens theevent handler listed by the EventWait function (step 119). Uponawakening, the event handler determines that the caller is the eventmonitor (and not an EventMonitorDelete function described below)(decisionblock 1120), calls an EventRetrieve function 56 to retrieve thealpha-numeric data stored in the current signal set (step 1121) and thenprocesses the event data (step 1122). Next, the event handler decideswhether any, all or none of the event signals in the current signal setshould be available for propagation, even though the event handler 14aneed not know if there are any other event monitors which are interestedin any of the events or even if the event definition specified thepropagation mode. If event handler 14a does not want to make any or allofthe event signals available for propagation in any case, the eventhandler 14a calls the EventDiscard function 58 specifying event monitor28a and any or all of the event signals in the current signal set to bediscarded.This will block any possible propagation of the specifiedevent signals from event monitor 28a's current signal set (step 1125).

When called, the EventDiscard function erases the specified signals fromthe current signal set of the named event monitor 28a (step 186 of FIG.3). Next, the EventDiscard function determines if the event signaller(s)of the discarded event signal(s) are in the wait state pursuant to thisattribute of the signalled event definition(s), and if so, awakens them(decision 188 and step 190). Then, the EventDiscard function returns tothe event handler (step 191). After step 191, or if decision block 1124indicates that the event handler made all the event signals availablefor propagation, the event handler can directly call theEventMonitorReset function illustrated in FIG. 4, or return to the eventmonitor which then calls the EventMonitorReset function. The eventhandler can also terminateitself in which case a function which assistsin the termination will call the EventMonitorReset function. Normally,the event handler makes the return to the event monitor after steps1120-1125. The event handler only calls the EventMonitorReset functiondirectly to indicate termination of processing prematurely, for example,to allow a trap routine to be re-entered, or to allow an event monitorto be polled successively with the EventTest function. Also, because anevent monitor is associated with an event handler, when the eventhandler is terminated, the event handler calls the EventMonitorResetfunction indirectly.

In step 172 of FIG. 4, the EventMonitorReset function reads the currentsignal set to identify any remaining signals. The current signal setwill be full if decision block 1124 led directly to step 1126, but willbe partially or completely empty if the event handler called theEventDiscardfunction in step 1125. If the current signal set is notempty (decision block 173), the EventMonitorReset function reads theevent definition for each event signal in the current signal set todetermine the mode of signalling of other interested event monitors(step 176). For each event signal, if the mode of signalling is thebroadcast mode (decision block 177), then the EventMonitorReset functionproceeds to step 180 to erase the event signal from the current signalset of the event monitor named inthe EventMonitorReset call (because theother interested event monitors already received the event signal).However, if the event definition indicates the FIFO or LIFO propagationmode for any of the event signals, then decision block 177 leads to step174 in which the EventMonitorReset function reads the other eventmonitor definitions to determine if any areinterested in that eventsignal (step 174). If so (decision block 175), then theEventMonitorReset function signals the next event monitor in thesequence for the respective event signal, and then proceeds to step 180.Thus, the event signals remaining in the current signal set for theeventswhich are defined for the propagation mode are propagated to thenext eventmonitor in the sequence for each event. That event monitoralso executes the sequence of steps 115-119 illustrated in FIG. 2, andthe respective event handler executes steps 1120-1126. After step 180,the EventMonitorReset function determines if the event monitor 28a hasbeen marked for deletion as described below (decision block 181). If so,the EventMonitorReset function calls an EventMonitorDelete function 68(step 185) described below. If not, or after receiving the return fromthe EventMonitorDelete function, the EventMonitorReset function returnsto itscaller (step 182).

FIG. 5 is a flowchart illustrating operation of the operating system 11when event handler 14c calls the EventTest function. In step 150, eitherthe event definer 12b or 13b defines Event B. Concurrently or at a latertime, event monitor definer 17b defines an event monitor 28b which isinterested in Event B (step 151). Next, event handler 14b calls theEventTest function 50 requesting status information about event monitor28b (step 153). In response, the EventTest function locates eventmonitor 28b (decision block 154), reads the bound signal set of eventmonitor 28b (step 155) and then determines if the event monitor issatisfied (decisionblock 156). If so, the EventTest function activatesthe event monitor and establishes the current signal set (step 157).After the event monitor returns to the Event Test function at step 158or if the event monitor wasnot satisfied, the EventTest function advisesthe event handler 14b whetherthe event monitor is satisfied, which eventsignals will be in the current signal set upon satisfaction of the eventmonitor, and the length of each signal (step 158). If event monitor 28bis satisfied (decision block 160),then the event handler will call theEventRetrieve function to obtain the event data (step 164), process thedata (step 166) and then execute steps 1124-1126 described above.However, if the event monitor was not satisfied, then the event handleravoids steps 164, 166 and 1124-1126, andcan perform other work.

FIG. 6A, B form a flowchart illustrating operation of the operatingsystem 11 when the EventTrap function 52 is called. In step 130, eitherevent definer 12b within the operating system 11 or event definer 13bwithin anyapplication program defines Event C. Concurrently, or at alater time, event monitor definer 17c defines an event monitor 28c whichis interestedin Event C (step 131). Next, event handler 14b calls theEventTrap function52 specifying that event monitor 28c should notify atrap routine within the event handler 14c when the event monitor issatisfied, and the name oraddress of the trap routine (step 132). Afterstep 132, the event handler 14b can perform other work; it does not idlywait for event notification in the event trap mode. In response to thecall, the EventTrap function sets an event trap bit and lists the traproutine's name or address with the event monitor 28c (step 133).Subsequently, Event C occurs, and event signaller 18b or 15b calls theEventSignal function 49 (step 134). Then, the EventSignal functionexecutes steps 102-114 as described above, and the event monitorexecutes step 115-117 as described above; however, step 117 indicatesthat the event wait bit has not been set. Therefore, the event monitorproceeds to determine that the event trap bit has been set (decisionblock 120), and then calls the trap routine within event handler14c(step 122). The trap routine calls the EventTest function 50 illustratedin FIG. 5 specifying the event monitor, event name and event key (step138). Then, the EventTest function executes steps 154-158 as describedabove. Based on the information received from the EventTest function,the trap routine determines that the event monitor has been located(decision block 139). Then, the trap routine calls the EventRetrievefunction to retrieve the event data from the current signal set (step140), processes the event data (step 142), and executes steps 1124-1126as described above. If the trap routine returns without having reset themonitor, the event monitor calls the EventMonitorReset function when itreceives the return from the event handler (step 128).

FIG. 7 is a flowchart illustrating broadcast of an event signal to twointerested event monitors. In step 380, an Event H is defined and thedefinition includes the name of the event and an indication that allinterested event monitors should be notified in the broadcast mode, i.e.substantially simultaneously. Concurrently or at a later time, the eventmonitor define 17a defines an event monitor 28a which is interested inEvent H (step 382), and event monitor definer 17b defines an eventmonitor28b which is also interested in Event H (step 384). The eventhandler 14a then calls the EventWait function and directs itself into asleep mode awaiting notification of Event H (step 386). The EventWaitfunction sets the wait bit for event monitor 28a and lists the callerfor event monitor 28a (step 387). Similarly, the event handler 14b callsthe EventWait function and directs itself into the sleep mode awaitingnotification of Event H (step 388). The EventWait function sets the waitbit for event monitor 28b and lists the caller for event monitor 28b(step 389). Subsequently, Event H occurs, and the event signaller callsthe EventSignal function 49 (step 390). In response, the EventSignalfunction executes steps 102-114 as described above, and in step 102determines thatthe broadcast mode has been specified. In step 110, theEventSignal function learns that two event monitors 28a and 28b are bothinterested inthe Event H. In step 114a, the EventSignal function signalsboth of the event monitors nearly at the same time; neither eventmonitor can prevent signalling to the other event monitor. Afterreceiving the event signal, event monitor 28a executes steps 115-119,and the associated event handler14a executes steps 1120-1126 asdescribed above. Similarly, after receivingthe event signal, eventmonitor 28b executes steps 115-119, and the associated event handler 14bexecutes steps 1120-1126 as described above. The respective eventmonitors 28a and 28b execute step 128. Therefore, after Event H occurs,both event handlers 14a and 14b receive the event notification and eventdata nearly simultaneously, and neither event handler can prevent theother event handler from receiving the event notification and eventdata.

FIG. 8 is a flowchart illustrating propagation of an event signal from afirst event monitor to a second event monitor in a sequence, with theright of the first event monitor in the sequence to prevent propagationofthe event signal to the second event monitor in the sequence. In step420, Event I is defined, and the definition includes the FIFOpropagation attribute which means that interested event monitors shouldbe signalled sequentially in order of creation. Concurrently or at alater time, event monitor definer 17c defines event monitor 28c which isinterested in EventI (step 422), and event monitor definer 17d definesevent monitor 28d whichis also interested in Event I (step 24). Asillustrated in FIG. 9, when each event monitor is created, it is chainedor referenced by address to the previously created event monitor whichis interested in the same event. This indicates the order of creation.After the event monitors are defined, event handler 14c calls theEventWait function specifying event monitor 28c (step 426), theEventWait function sets the wait bit and liststhe caller (step 429),event handler 14d calls the EventWait function specifying the eventmonitor 28d (step 428) and the EventWait function sets the wait bit andlists the caller (step 429). Subsequently, Event I occurs, and the eventsignaller calls the EventSignal function 49 (step 430). In response, theEventSignal function executes steps 102-114, and instep 102 notes fromthe event definition that the FIFO propagation mode hasbeen specified.In step 110, the EventSignal function also learns that event monitors28c and 28d are both interested in Event I, and from the order ofchaining of the event monitors that event monitor 28c was createdfirst.Then, in step 114b, the EventSignal function signals the firstinterested event monitor in the sequence, event monitor 28c. Then, eventmonitor 28c executes steps 115-119, and in step 119 awakens eventhandler 14c. Then, the event handler 14c executes steps 1120-1124 and1126, and indecision block 1124 decides that the event signal should beavailable for propagation. Then, the event handler 14c returns to theevent monitor in step 1126 which automatically calls theEventMonitorReset function (step 128). However, the event handler 14ccould have decided in decision block 1124 that any or all of the eventsignals in the current signal set shouldnot be available for propagationand then call the EventDiscard function 58specifying which ones shouldbe discarded. If in step 1125, event handler 14c specifies that all theevent signals in the current signal set should be discarded (which inthe illustrated example is the lone signal for Event I), then in step186 of FIG. 3, they are discarded and the EventMonitorReset functionwould not propagate anything to event monitor 28d because the currentsignal set would be empty (decision block 173 of FIG. 4). In theillustrated example, however, event handler 14c does not discard thesignal for Event I, event monitor 28c is reset, and theEventMonitorReset function signals the event monitor 28d in step 178 ofFIG. 4 which executes steps 115-119. Then, event handler 14d executessteps 1120-1126. If event handler 14d discards Event I in step 1125,then when the EventMonitorReset function is called, decision block 173of FIG. 4 would avoid an attempt at propagating the event signal becausethe current signal set would be empty. If event handler 14d does notdiscard Event I in step 1125, then when the EventMonitorReset functionis called, decision block 175 would avoid an attempt at propagationbecause there areno more interested event monitors.

FIG. 10 illustrates a more complicated example of chaining of eventmonitors to indicate order of propagation. Event monitor 28e isinterestedin Events M, N and 0, and was created first. Event monitor 28fwas created after event monitor 28e, is interested in events M and P andis chained from the Event M reference in event monitor 28e to indicatethat both event monitors are interested in Event M. Event monitor 28gwas also created after event monitor 28e, is interested in the events Nand 0, and is chained from the event N and event O references in eventmonitor 28e toindicate that both event monitors are interested in EventsN and O. Similarly, event monitors 28h and 28i were created after eventmonitor 28f, are interested in events M and P, respectively, and arechained from the respective event M and event P references in the eventmonitor 28f. Thus, when it is necessary to propagate each event signalfrom any of these event monitors, the EventMonitorReset function readsthe event monitor definition to identity the next event monitor in theFIFO or LIFO sequence that is interested in the particular event.

At any time after defining an event, the process which defined the eventcan delete or modify the event definition by calling an EventDeletefunction 69 or an EventModify function 71. The EventDelete function isillustrated in FIG. 11. The EventDelete function does not affect currentprocessing of the current signal set, but reads the bound signal set foreach event monitor which is interested in the event to be deleted andthe loose signal set 41 for the event to determine if there are anyevent signals which are not in the current signal set (decision block296). If so, they are discarded (step 298). Next, the EventDeletefunction indicates in the definition of each event monitor which isinterested in the event that the event has been deleted (step 300).Then, the EventDelete function determines if there are any eventmonitors which are interested in the event and have outstandingEventWaits (decision block 302). If so, the EventDelete function callsthe event monitor at step 119 (step 303) and steps 120-128 are executed.In step 120, the event handler will learn that the event has beendeleted and consequently that the eventmonitor associated with the eventhandler may never be satisfied. Next, theEventDelete function determinesif there are any event monitors which are interested in the event andhave outstanding event traps (decision block 304). If so, theEventDelete function calls the event monitor(s) at step 122 (step 305),and then steps 138-142 and 1124-1126 are executed. In step158 of theEventTest function (which was called by the trap routine in step138),the EventTest function notifies the trap routine that the event monitormay never be satisfied. Finally, the EventDelete function deletes theevent definition (step 306).

The EventModify function is called to change the loose signal limit oroperational status of signalling attributes within the event definition.Changes to the loose signal limit attribute take effect immediatelywhereas changes to the operational status attribute do not take effectuntil a subsequent signal is issued.

When an event is originally created, it is automatically enabled. TheEventEnable function 44 can be called to disable an event after theevent is created or to enable a disabled event. When an event isdisabled, signals for the event are bound to the interested eventmonitor(s) but do not count toward satisfaction of the event monitor(s).

FIG. 12 is a flowchart illustrating the EventEnable function. In step202, the event definer 13a defines Event D, and in step 204 the eventmonitor definer 17d defines event monitor 28d which is interested inEvent D. Next, the event handler 14d which is associated with eventmonitor 28d cancall the EventEnable function and specify that Event Dshould be disabled (step 206). In response, the EventEnable functionmarks the event definition for Event D as disabled (step 208).Subsequently, Event D occurs, the event signaller calls the EventSignalfunction (step 210), andthe EventSignal function executes steps 102-114as described above. Then, the event monitor binds the event signal toevent monitor 28d but indicates that the event signal should not counttoward satisfying the event monitor (decision block 212 and step 213).Then, the event monitor proceeds to step 116 and subsequent steps117-119 as described above in FIG. 2, but in step 116 does not count thelatest occurrence of Event D toward satisfaction of the event monitor.

As noted above, when an event monitor is originally created, it isautomatically enabled. However, the EventMonitorEnable function 64 canbe called to disable an event monitor after creation, or enable adisabled event monitor. Event signals will be bound to a disabled eventmonitor, but a disabled event monitor cannot be satisfied.

FIG. 13 is a flowchart illustrating the EventMonitorEnable function.After Event E is created (step 220), and an interested event monitor iscreated (step 222), the event handler can call the EventMonitorEnablefunction specifying that the named event monitor should be disabled(step 224). In response, the EventMonitorEnable function marks theEventMonitor definition with a disabled indicator (step 226). When EventE occurs, the event signaller calls the EventSignal function (step 228),and the EventSignal function executes steps 102-114 as described above.Then, the event monitor binds the event signal to the event monitor(step 115), but on account of the disabled indicator in the eventmonitor definition, the event monitor does not count this or any signaltoward satisfaction of theevent monitor in decision block 116, and nofurther action is taken by the event monitor.

When an event is originally defined, monitoring is automaticallystarted. If the monitoring remains started, the EventSignal functionsignals the interested event monitor(s) in the manner described above inFIGS. 2, 5 and 6a, b. However, an EventSelect function 60 can be calledto stop monitoring specific events, or to start monitoring aftermonitoring has been stopped. When monitoring is stopped, subsequentevent signals are notbound to any event monitor in the process whichissued the EventSelect function.

FIG. 14 illustrates the EventSelect function. In step 250, the Event Fis defined and monitoring is automatically started. Then, the eventmonitor is defined (step 252). Subsequently, the event handler calls theEventSelect function and specifies that monitoring of a named eventshouldbe stopped (step 254). In response, the EventSelect function marksthe event definition for the named event as monitoring stopped (step256). Subsequently, Event F occurs, and the event signaller calls theEventSignal function (step 258). The EventSignal function executes steps102 and 104 as described above, and then determines from the eventdefinition that monitoring should be stopped (decision block 106).Consequently, the EventSignal function binds the event signal to theeventdefinition in accordance with the loose signal limit within theevent definition (step 262). Because monitoring has been stopped, theEventSelect function does not signal any event monitor, not even theinterested event monitor.

When any event monitor is initially created, monitoring is automaticallystarted for the event monitor. However, the EventMonitorSelect function66can be called to stop monitoring by an event monitor, or to Startmonitoring by a stopped event monitor. The EventMonitorSelect function66 differs from the EventMonitorEnable function 64 because the signal ofinterest to a stopped event monitor is not bound to the event monitor,whereas the signal of interest to a disabled event monitor is bound totheevent monitor.

FIG. 15 is a flowchart illustrating the EventMonitorSelect function. Instep 270, Event G is defined, and in step 272 an interested eventmonitor 28b is defined. In step 274, the event handler 14b calls theEventMonitorSelect function specifying that event monitor 28b shouldstop monitoring. In response, the EventMonitorSelect function marks theevent monitor definition as monitoring stopped (step 276). After Event Goccurs and the event signaller calls the EventSignal function (step278), the EventSignal function executes steps 102-114 as described aboveand in decision block 112, determines that monitoring for event monitor28b has been stopped. As a result, the EventSignal function binds theevent signalto the event definition for Event G but does not signalevent monitor 28b or bind the signal to event monitor 28b. It should benoted, that if thereare other event monitors which are interested inEvent G and have their monitoring started, then these other eventmonitors would receive the event signal in step 112, and the eventsignal would not be bound to the event definition.

At any time after creation of an event monitor, the process that createdthe event monitor can also delete the event monitor by calling anEventMonitorDelete function 68 illustrated in FIG. 16. When a process isterminated, the process calls the EventMonitorDelete function to deleteall of the event monitors that were defined by the process. In step 400,the EventMonitorDelete function reads the information (definition, boundsignals, status, etc.) associated with the event monitor. If the eventmonitor is active (decision block 402), the EventMonitorDelete functionmarks the event monitor with an indication that the event monitor shouldbe deleted when it is next reset (step 404), which causes theEventMonitorReset function to call the EventMonitorDelete functionduring step 185 of FIG. 4. However, the EventMonitorDelete function doesnot interfere with processing of the current signal set. If the eventmonitor was found to be inactive in decision block 402, or after theevent monitorbecomes inactive after processing of the current signal setand a subsequent execution of the EventMonitorReset function, theEventMonitorDelete function removes the event monitor from the chain sothat it is no longer accessible to any other function (step 406). Next,the EventMonitorDelete function determines if any of the events in whichthe event monitor is interested are defined with the propagationattributeand if there are any other interested, downstream eventmonitors (decision block 408). If both conditions are satisfied, thenthe EventMonitorDelete function propagates each bound event signal thatmeets these conditions tothe next event monitor in the respectivesequence (step 410). The EventMonitorDelete function discards any boundsignals that do not meet both criteria (step 412). Next, theEventMonitorDelete function reads the event wait bit in the eventmonitor to determine if there is an EventWait outstanding (decisionblock 414). If so, the EventMonitorDelete function awakens therespective event handler and indicates that the event monitor is beingdeleted (step 416). Next, the EventMonitorDelete function reads the trapbit to determine if there is an event trap outstanding (decision block418). If so, the EventMonitorDelete function invokes the trap routine(step 420). When the trap routine invokes the EventTest function (step138 of FIG. 6, the EventTest function will not locate the event monitorin decision block 139 of FIG. 6 and report to the trap routine that theevent monitor does not exist. Then, the trap routine will return to theoperating system, and the operating system implicitly calls theEventMonitorReset function. Finally, the EventMonitorDelete functionerases the event monitor definition (step 422).

In an alternate embodiment of the present invention, any of theattributes of an existing event monitor, including the events ofinterest to the event monitor, can be dynamically modified. If an eventtype is deleted from a list of events of interest to the event monitor,then bound signalsof the deleted event type are processed as describedin the EventMonitorDelete function 68. If an event type is added to theevent monitor definition, then any loose signals of that event type areprocessed as described in the EventMonitorCreate function 42. In fact,theevent monitor modification is functionally equivalent to atomicallydeleting the event monitor with the EventMonitorDelete function 68 andrecreating the event monitor with the EventMonitorCreate function 42with the following exceptions. Bound signals of events that are ofinterest to the event monitor both before and after the modification areneither discarded nor propagated except if the bound signal limit isdecreased andthere are more bound signals than the decreased limit, inwhich case the excess oldest bound signals are discarded. Also, becausethe event monitordefinition is modified atomically (i.e. in one step),there is no possibility of losing signals for events that occur whilethe event monitor definition is being modified.

    ______________________________________                                        EVENT SIGNAL MANAGER FUNCTION CALLS                                           ______________________________________                                        EventCreate       retcode                                                                       rsncode                                                                       event.sub.-- name                                                             event.sub.-- name.sub.-- length                                               event.sub.-- flag                                                             event.sub.-- flag.sub.-- size                                                 loose.sub.-- signal.sub.-- limit                                              signal.sub.-- timeout.sub.-- period                         ______________________________________                                    

Parameters: "EventCreate" is the name of the function being invoked."Retcode" is a signed 4-byte binary variable to hold the return codefrom EventCreate. A "return code" indicates success or failure or erroror lackof error of a call or parameter. "Rsncode" is a signed 4-bytebinary variable to hold the reason code from EventCreate. A "reasoncode" indicates the reason for a failure or error of a call orparameter. "Eventname" is a character variable containing the name ofthe event to be defined. "Event₋₋ name₋₋ length" is a signed 4-bytebinary variable containing the length of event₋₋ name. "Event flag" isan array of 4-byte binary variables each element of which containsinformation about how the event is to be managed. Only one option fromeach of the following sets may be specified. If no option from aparticular set is specified, the default is taken. The scope of theevent name is indicated by process and session; "vm₋₋ evn₋₋ process₋₋scope" where only this process can monitor this event and only thisprocess can signal this event, and "vm₋₋ evn₋₋ session₋₋ scope" whereall processes in the session can both monitor and signal this event. Themanner in which an event signal is delivered tomultiple event monitorsin a process is indicated as broadcast, FIFO or LIFO mode; "vm₋₋ evn₋₋broadcast₋₋ signals" where the signal is delivered simultaneously to allqualifying monitors, "vm₋₋ evn₋₋ fifo₋₋ signals" where the signal isdelivered to one qualifying monitor at a time, in the order the monitorswere created, and "vm₋₋ evn₋₋ lifo₋₋ signals" where the signal isdelivered to one qualifying monitor at a time, in the order oppositethat of event defined with the FIFO option.

The treatment of the signaler is indicated as "vm₋₋ evn₋₋ async₋₋signals", "vm evn sync₋₋ thread₋₋ signals", or "vm₋₋ evn₋₋ sync₋₋process₋₋ signals". The vm₋₋ evn₋₋ async₋₋ signals indicates that thesignaling thread is allowed to continue executing (the default). Thevm₋₋ evn₋₋ sync₋₋ thread₋₋ signals indicates that the signaling threadis suspended until signal processing is complete. Signal processing in aprocess is considered complete when all qualifying monitors havecompletedprocessing of the signal or, if there are no qualifyingmonitors, the signal has been discarded as a result of being the oldestloose signal when the loose signal limit was exceeded. An event monitoris considered to have completed processing a signal when that signal hasbecome part of the current signal set of the event monitor and thatevent monitor has subsequently been reset. For FIFO and LIFO events, abound signal may be explicitly discarded via EventDiscard or implicitlydiscarded if it is theoldest bound signal when the bound signal limit ofthe event name-event keypair to which it is bound is exceeded. In eithercase, the processing of the discarded signal by that process isconsidered complete. If this is a session level event, all processesmust have completed processing before signal processing is consideredcomplete. The vm₋₋ evn₋₋ sync₋₋ process₋₋ signals indicate that allthreads currently existing in the signaling process, with the exceptionof those threads running as the result of an event monitor activated bythis signal, are suspended to await the outcome of event processing.Threads running as theresult of event monitor activation may createadditional threads which are not initially suspended. UponEventMonitorReset however, the additional threads are treated as anyother thread.

"Event₋₋ flag₋₋ size" is a signed 4-byte binary variable containing thenumber of elements in the event₋₋ flag array.

"Loose₋₋ signal₋₋ limit" is a signed 4-byte binary variable containingthe number of event signals that may be retained if no eligibleeventmonitor exists to which to bind the signal at the time the event issignaled. When the limit is exceeded, the oldest loose signal isdiscardedto make room for the newest arrival. A value of 0 indicatesthat no loose signals are to be retained. A value of -1 means that theloose signal listis allowed to grow without limit, subject to theavailability of virtual storage. Any other negative value is consideredan error.

"Signal₋₋ timeout₋₋ period" is a signed 4-byte binary variablerepresenting the maximum length of time, specified in microseconds, thatasignaling thread should remain suspended awaiting the completion ofprocessing of the signal. A value of 0 indicates that the signalingthreadshould wait indefinitely for the completion of signal processing.If the option specifying that the Signalling thread is to continueprocessing is included in the event₋₋ flag array, then this parameter isignored.

    ______________________________________                                        Event Delete      retcode                                                                       rsncode                                                                       event.sub.-- name                                                             event.sub.-- name.sub.-- length                             ______________________________________                                    

Parameters: "EventDelete" is the name of the function being invoked."Retcode" is a signed 4-byte binary variable to hold the return codefrom EventDelete. "Rsncode" is a signed 4-byte binary variable to holdthe reason code from the EventDelete. "Event name" is a charactervariable containing the name of the event whose definition is to bedeleted. "Event₋₋ name₋₋ length" is a signed 4-byte binary variablecontaining the length of event₋₋ name.

    ______________________________________                                        EventDiscard        retcode,                                                                      rsncode,                                                                      monitor.sub.-- token,                                                         index                                                     ______________________________________                                    

Parameters: "EventDiscard" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventDiscard.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventDiscard.

"Monitor token" is a signed 4-byte binary variable containing the tokenwhich identifies the event monitor from whose current signal set asignal is to be discarded. A value of 0 may be used to identify theactive event monitor which was most recently activated on the currentthread.

"Index" is a signed 4-byte binary variable identifying, as an index intothe event₋₋ name₋₋ address, event₋₋ name₋₋ length, event₋₋ key₋₋address, and event₋₋ key₋₋ length arraysspecified in the creation of theevent monitor, the event₋₋ name and event₋₋ key pair corresponding tothe signal to be discarded. A valueof 0 may be used to indicate that allsignals in the current signal set areto be discarded.

    ______________________________________                                        EventEnable      retcode                                                                       rsncode                                                                       number.sub.-- of.sub.-- events                                                event.sub.-- name.sub.-- address                                              event.sub.-- name.sub.-- length                                               event.sub.-- enablement.sub.-- mask                          ______________________________________                                    

Parameters:

"EventEnable" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return code forEventEnable.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventEnable.

"Number₋₋ of₋₋ events" is a signed 4-byte binary variable containing thenumber of event₋₋ name and event₋₋ key pairs of interest.

"Event₋₋ name₋₋ address" is an array of number of events 4-byte pointervariables each element of which contains the address of the name of anevent whose occurrence is to be monitored.

"Event₋₋ name₋₋ length" is an array of number₋₋ of₋₋ events signed4-byte binary variables each element of which contains the length of theevent₋₋ name pointed to by the corresponding element ofthe event₋₋name₋₋ address array.

"Event₋₋ enablement₋₋ mask" is an array of number₋₋ of₋₋ events signed4-byte binary variables each element of which contains the enablementmask of the event name pointed to by the corresponding element of theevent₋₋ name₋₋ address array. The event enablement mask is maintained ona process basis; the EventEnable command affects the issuing processonly. The value of the enablement maskdetermines the action to beperformed, i.e.

"vm evn disable" which disables the event₋₋ name indicated by thecorresponding element of the event₋₋ name₋₋ address array, or

"vm evn enable" which enables the event₋₋ name indicated by thecorresponding element of the event₋₋ name₋₋ address array.

    ______________________________________                                        EventModify       retcode                                                                       rsncode                                                                       event.sub.-- name                                                             event.sub.-- name.sub.-- length                                               event.sub.-- flag                                                             event.sub.-- flag.sub.-- size                                                 loose.sub.-- signal.sub.-- limit                                              signal.sub.-- timeout.sub.-- period                         ______________________________________                                    

Parameters:

"EventModify" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventModify.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventModify.

"Event name" is a character variable which contains the name of theevent whose definition is to be modified.

"Event₋₋ name₋₋ length" is,a signed 4-byte binary variable containingthe length of event name.

"Event₋₋ flag" is an array of 4-byte binary variables each element ofwhich contains information about how the event is to be managed. Onlyone option from the following set may be specified. If no option fromthis setis specified, the existing value of the option remainsunmodified. The treatment of the signaler is indicated by vm₋₋ evn₋₋async₋₋ signals in which the signaling thread is allowed to continueexecuting (the default), vm₋₋ evn₋₋ sync₋₋ thread₋₋ signals in which thesignaling thread is suspended to await the outcome ofevent processing,or vm₋₋ evn₋₋ sync₋₋ process₋₋ signals in which all threads in thesignaling process, with the exception of those threads running as theresult of a monitor activated by this signal, are suspended to await theoutcome of event processing.

"Event₋₋ flag₋₋ size" is a signed 4-byte binary variable containing thenumber of elements in the event₋₋ flag₋₋ array.

"Loose₋₋ signal₋₋ limit" is a signed 4-byte binary variable containingthe number of event signals which may be retained if no eligible eventmonitor exists to which to bind the signal at the time the event issignaled. When the limit is exceeded, the oldest loose signal isdiscarded to make room for the newest arrival. A value of 0 indicatesthatno loose signals are to be retained. A value of -1 means that theloose signal limit will be allowed to grow without limit, subject to theavailability of virtual storage. A value of -2 means that the existingloose₋₋ signal₋₋ limit is to remain unmodified. Any other negative valueis considered an error.

"Signal₋₋ timeout₋₋ period" is a signed 4-byte binary variablerepresenting the maximum length of time, specified in microseconds, thatasignaling thread should remain suspended awaiting the completion ofprocessing of the signal. A value of 0 indicates that the signalingthreadshould wait indefinitely for the completion of signal processing.A value of -1 means that the existing signal₋₋ timeout₋₋ period is toremain unmodified. If the option specifying suspension of the signaleris not included in the event₋₋ flag array, then this parameter isignored.

    ______________________________________                                        EventMonitorCreate  retcode                                                                       rsncode                                                                       monitor.sub.-- token                                                          monitor.sub.-- flag                                                           monitor.sub.-- flag.sub.-- size                                               number.sub.-- of.sub.-- events                                                event.sub.-- name.sub.-- address                                              event.sub.-- name.sub.-- length                                               event.sub.-- key.sub.-- address                                               event.sub.-- key.sub.-- length                                                bound.sub.-- signal.sub.-- limit                                              event.sub.-- count                                        ______________________________________                                    

Parameters:

"EventMonitorCreate" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventMonitorCreate.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventMonitorCreate.

"Monitor₋₋ token" is a signed 4-byte binary variable in which isreturned a token with which to identify the event monitor on subsequentinvocations of other event management functions.

"Monitor₋₋ flag" is an array of signed 4-byte binary variables eachelement of which contains information about how the event monitor is tobemanaged. Only one option from each of the following sets may bespecified. If no option from a particular set is given, the default isapplied.

The longevity of the monitor is indicated by "vm₋₋ evn₋₋ no₋₋ auto₋₋delete" which means that the event monitor persists until explicitEventMonitorDelete (the default), or "vm₋₋ evn₋₋ auto₋₋ delete" whichmeans that the event monitor is automatically deleted at firstdeactivation or EventMonitorReset. The effect of monitor activation ondispatchability is indicated by "vm₋₋ evn₋₋ async₋₋ monitor" which meansthat all threads in the process containing the monitor remaindispatchable (the default), or "vm₋₋ evn₋₋ sync₋₋ process₋₋ monitor"which means that all threads currently existing in the processcontaining the monitor, except the one on which the monitor is beingactivated (i.e. the event handler for this event monitor), are suspendeduntil the monitor is deactivated. The binding of loose signals to thismonitor is indicated by "vm₋₋ evn₋₋ bind₋₋ loose₋₋ signals" (thedefault) which means that when the monitor is created, or monitoring isrestarted via EventSelect or EventMonitorSelect, any loose signals forwhich this monitor is qualified are bound to this monitor, or "vm₋₋evn₋₋ ignore₋₋ loose₋₋ signals" which means that no loose signals arebound to this monitor.

"Monitor₋₋ flag₋₋ size" is a signed 4-byte binary variable containingthe number of elements in the monitor₋₋ flag array.

"Number₋₋ of₋₋ events" is a signed 4-byte binary variable containing thenumber of event₋₋ name and event₋₋ key pairs of interest.

"Event₋₋ name₋₋ address" is an array of number₋₋ of₋₋ events 4-bytepointer variables each element of which contains the addressof the nameof an event whose occurrence is to be monitored.

"Event₋₋ name₋₋ length" is an array of number₋₋ of₋₋ events signed4-byte binary variables each element of which contains the length of theevent₋₋ name pointed to by the corresponding element ofthe event₋₋name₋₋ address array.

"Event₋₋ key₋₋ address" is an array of number₋₋ of₋₋ events 4-bytepointer variables each element of which contains the addressof a keythat further characterizes the particular instance of the event₋₋ namepointed to by the corresponding entry of the event₋₋ name₋₋ addressarray that is to be monitored. The key may be chosen to match exactlythe key that will be carried by the signalsof interest; or a partialkey, possibly including wildcard characters, may be used to match abroader range of occurrences. "Event₋₋ key₋₋ length" is an array ofnumber₋₋ of₋₋ events signed 4-byte binaryvariables each element of whichcontains the length of the event₋₋ keypointed to by the correspondingelement of the event₋₋ key₋₋ address array. The key may be null (thatis, its length may be 0) if no secondary characterization of the eventis required to define the occurrence of interest; a null key in amonitor matches any key on a signal.

"Bound₋₋ signal₋₋ limit" is an array of number₋₋ of₋₋ events signed4-byte binary variables each element of which contains the number ofsignals of the corresponding event name and event key pair that may beretained bound to the event monitor but unprocessed during an intervalwhen the monitor is already active or testable or while the monitoredcondition remains unsatisfied. When the limit is exceeded, the oldestbound signal of a particular event₋₋ name and event₋₋ keypair isdiscarded to make room for the newest arrival. The minimum permissiblevalue is 1, indicating that only the most recent instance of each signalis to be retained. A value of -1 means that the bound signal list is tobe allowed to grow without limit, subject to the availability of virtualstorage. Any other negative value, or 0, is considered an error.

"Event₋₋ count" is a signed 4-byte binary variable that contains thenumber of the specified event₋₋ name and event₋₋ key pairs for whichsignals must be bound to the monitor for the monitored condition to beconsidered satisfied. The value must fall between 1 and number₋₋ of₋₋events. Alternately, in another embodiment of the present invention, anevent₋₋ count is specified for each event type to indicate the number ofoccurrences of each event type required to satisfy the event monitor.

    ______________________________________                                        EventMonitorDelete   retcode                                                                       rsncode                                                                       monitor.sub.-- token                                     ______________________________________                                    

Parameters:

"EventMonitorDelete" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventMonitorDelete.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventMonitorDelete.

"Monitor₋₋ token" is a signed 4-byte binary variable containing thetoken which identifies the event monitor to be deleted. A value of 0 maybe used to identify the active event monitor which was most recentlyactivated on the current thread.

    ______________________________________                                        EventMonitorEnable                                                                             retcode                                                                       rsncode                                                                       number.sub.-- of.sub.-- monitors                                              monitor.sub.-- tokens                                                         monitor.sub.-- enablement.sub.-- masks                       ______________________________________                                    

Parameters:

"EventMonitorEnable" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventMonitorEnable.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventMonitorEnable.

"Number₋₋ of₋₋ monitors" is a signed 4-byte binary variable containingthe number of monitor₋₋ tokens of interest.

"Monitor₋₋ tokens" is an array of number of monitors 4-byte pointervariables each element of which contains the token of the monitor whichisto be enabled or disabled. A value of 0 may be used to identify theactive event monitor which was most recently activated on the currentthread.

"Monitor₋₋ enablement₋₋ masks" is an array of number₋₋ of₋₋ monitorssigned 4-byte binary variables each element of which contains theenablement mask for the monitor identified by the corresponding elementof the monitor₋₋ tokens array. The value of theenablement maskdetermines the action to be performed; i.e. "vm₋₋ evn₋₋ disable" causesthe disabling of the monitor identified by the corresponding element ofthe monitor₋₋ tokens array, and "vm₋₋ evn₋₋ enable" causes the enablingof the monitor identified by the corresponding element of the monitor₋₋tokens array.

EventMonitorQuery--An application program can call this function toobtain information about the definition and status of a previouslycreated event monitor.

    ______________________________________                                        EventMonitorQuery                                                                              retcode                                                                       rsncode                                                                       monitor.sub.-- token                                                          monitor.sub.-- flag                                                           monitor.sub.-- flag.sub.-- size                                               monitor.sub.-- flag.sub.-- count                                              number.sub.-- of.sub.-- events                                                event.sub.-- name.sub.-- buffer.sub.-- address                                event.sub.-- name.sub.-- buffer.sub.-- length                                 event.sub.-- name.sub.-- length                                               event.sub.-- key.sub.-- buffer.sub.-- address                                 event.sub.-- key.sub.-- buffer.sub.-- length                                  event.sub.-- key.sub.-- length                                                bound.sub.-- signal.sub.-- limit                                              bound.sub.-- signal.sub.-- count                                              monitor.sub.-- selection.sub.-- mask                                          monitor.sub.-- enablement.sub.-- mask                                         event.sub.-- count                                                            present.sub.-- event.sub.-- count                                             trap.sub.-- routine.sub.-- address                                            trap.sub.-- routine.sub.-- name                              ______________________________________                                    

Parameters:

"EventMonitorQuery" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventMonitorQuery.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventMonitorQuery.

"Monitor₋₋ token" is a signed 4-byte binary variable identifying theevent monitor about which information is to be returned. A value of 0may be used to identify the active event monitor which was most recentlyactivated on the current thread.

"Monitor₋₋ flag" is an array of signed 4-byte binary variables ineachelement of which is returned information about how the event monitoris to be managed. Exactly one option from each of the following sets isincluded.

The longevity of the monitor is indicated either by "vm₋₋ evn₋₋ no₋₋auto₋₋ delete" which means that the event monitor persists untilexplicit EventMonitorDelete or termination of the defining process, or"vm₋₋ evn₋₋ auto₋₋ delete" which means that the event monitor isautomatically deleted at first deactivation or EventMonitorReset call.

The effect of monitor activation on dispatchability is indicated by"vm₋₋ evn₋₋ async₋₋ monitor" which means that all threads in the processcontaining the monitor remain dispatchable (the default), or "vm₋₋ evn₋₋sync₋₋ process₋₋ monitor" which means that all threads currentlyexisting in the process containing the monitor,except the one on whichthe monitor is being activated (i.e. the event handler for this eventmonitor), are suspended until the monitor is deactivated.

The binding of loose signals to this monitor is indicated either by"vm₋₋ evn₋₋ bind₋₋ loose₋₋ signals" which means that any qualifyingloose signals that exist at the time the monitor is createdorselected-on are bound to the event monitor (the default), or "vm₋₋ evn₋₋ignore₋₋ loose₋₋ signals" which means that no loose signals are bound tothe monitor.

The current activation state of the monitor is indicated by "vm₋₋ evn₋₋monitor₋₋ active" which means that the monitored conditionis satisfiedand a signal processing program is executing; "vm₋₋ evn₋₋ monitor₋₋waiting" which means that the monitor is not active, the monitoredcondition is not satisfied and there is an outstanding EventWaitassociated with the monitor; "vm₋₋ evn₋₋ monitor₋₋ trapping" which meansthat the monitor is neither active nor waiting, the monitored conditionis not satisfied, and there is a traproutine associated with themonitor; or "vm₋₋ evn₋₋ monitor₋₋ testable" which means that the monitoris not active, waiting or trapping, the monitored condition may or maynot be satisfied, and there is neither an outstanding EventWait or traproutine associated with the monitor.

"Monitor₋₋ flag₋₋ size" is a signed 4-byte binary variable containingthe number of elements in the monitor₋₋ flag array.

"Monitor₋₋ flag₋₋ count" is a signed 4-byte binary variable in which isreturned the number of elements in the monitor₋₋ flag array which havebeen set by EventMonitorQuery.

"Number₋₋ of₋₋ events" is a signed 4-byte binary variable containing thenumber of event₋₋ name and event₋₋ key pairs of interest.

"Event₋₋ name₋₋ buffer₋₋ address" is an array of number₋₋ of₋₋ events4-byte pointer variables each element of which contains the address of acharacter variable in which is to be returned the name of an event whoseoccurrence is to be monitored.

"Event₋₋ name₋₋ buffer₋₋ length" is an array of number₋₋ of₋₋ eventssigned 4-byte binary variables each elementof which contains the lengthof the event₋₋ name₋₋ buffer pointedto by the corresponding element ofthe event₋₋ name₋₋ buffer₋₋ address array.

"Event₋₋ name₋₋ length" is an array of number₋₋ of₋₋ events signed4-byte binary variables in each element of which is returnedthe actuallength of the event₋₋ name which has been stored in the buffer pointedto by the corresponding element of the event₋₋ name₋₋ buffer₋₋ addressarray. If the name is longer than the buffer, it is truncated; ifshorter, the excess space at the end of the buffer is unchanged.

"Event₋₋ key₋₋ buffer₋₋ address" is an array of number₋₋ of₋₋ events4-byte pointer variables each element of which contains the address of abuffer in which to return the key that further characterizes theparticular instance of the event₋₋ name pointed to by the correspondingentry of the event₋₋ name₋₋ buffer₋₋ array which is being monitored.

"Event₋₋ key₋₋ buffer₋₋ length" is an array of number₋₋of₋₋ eventssigned 4-byte binary variables each element of which contains the lengthof the buffer pointed to by the corresponding element of the event₋₋key₋₋ buffer₋₋ address array.

"Event₋₋ key₋₋ length" is an array of number₋₋ of₋₋ events signed 4-bytebinary variables in each element of which is returnedthe actual lengthof the event₋₋ key which has been stored in the buffer pointed to by thecorresponding element of the Event₋₋ key₋₋ buffer₋₋ address array. Ifthe key is longer than the buffer, it is truncated; if shorter, theexcess space at the end of the buffer is unchanged.

"Bound₋₋ signal₋₋ limit" is an array of number of events signed 4-bytebinary variables in each element of which is returned the numberofsignals of the corresponding event name and event key pair which maybe retained bound to the event monitor but unprocessed during aninterval when the monitor is already active or testable or while themonitored condition remains unsatisfied. When the limit is exceeded theoldest boundsignal of a particular event₋₋ name and event₋₋ key pair isdiscarded to make room for the newest arrival. The minimum permissiblevalue is 1, indicating that only the most recent instance of each signalis to be retained. A value of -1 means that the bound signal list isallowed to grow without limit, subject to the availability of virtualstorage.

"Bound₋₋ signal₋₋ count" is an array of number₋₋ of₋₋ events signed4-byte binary variables in each element of which is returnedthe numberof signals of the corresponding event name and event key pair which arecurrently bound to the event monitor but unprocessed.

"Monitor₋₋ selection₋₋ mask" is a 4-byte variable in which is returnedthe selection mask for this monitor. This variable indicates whetherthis monitor is selected off or is selected on.

"Monitor₋₋ enablement₋₋ mask" is a 4-byte binary variable in which isreturned the enablement mask for this monitor. This variable indicateswhether this monitor is disabled or is enabled.

"Event₋₋ count" is a signed 4-byte binary variable in which is returnedthe number of the specified event₋₋ name and event₋₋ key pairs for whichsignals must be bound to the monitor for the monitoredcondition to beconsidered satisfied.

"Present₋₋ event₋₋ count" is a signed 4-byte binary variable in which isreturned the number of the specified event₋₋ name and event₋₋ key pairsfor which signals are currently bound to the event monitor.

"Trap₋₋ routine₋₋ address" is a 4-byte binary variable in which isreturned the address of a routine to be invoked when the conditiondefined by the monitor is satisfied, as established by the EventTrapfunction. If no address has been established by EventTrap, a value of 0isreturned.

"Trap₋₋ routine₋₋ name" is an 8-byte variable in which is returned thename of a routine to be invoked when the condition defined bythe monitoris satisfied, as established by the EventTrap function, or blank if noevent trap is associated with the monitor.

    ______________________________________                                        EventMonitorReset    retcode                                                                       rsncode                                                                       monitor.sub.-- token                                     ______________________________________                                    

Parameters:

"EventMonitorReset" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventMonitorReset.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventMonitorReset.

"Monitor₋₋ token" is a signed 4-byte binary variable containing thetoken that identifies the monitor whose state is to be reset. A value of0may be used to identify the active event monitor most recentlyactivated onthe current thread.

    ______________________________________                                        EventMonitorSelect                                                                             retcode                                                                       rsncode                                                                       number.sub.-- of.sub.-- monitors                                              monitor.sub.-- tokens                                                         monitor.sub.-- selection.sub.-- masks                        ______________________________________                                    

Parameters:

"EventMonitorSelect" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventMonitorSelect.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventMonitorSelect.

"Number₋₋ of₋₋ monitors" is a signed 4-byte binary variable containingthe number of monitor tokens of interest.

"Monitor₋₋ tokens" is an array of number₋₋ of₋₋ monitors 4-byte binaryvariables each element of which contains the token of the monitor whichis to be selected on or off. A value of 0 may be used to identify theactive event monitor which was most recently activated on thecurrentthread.

"Monitor₋₋ selection₋₋ masks" is an array of number₋₋ of₋₋ monitorssigned 4-byte binary variables each element of which contains theselection mask for the monitor identified by the corresponding elementof the monitor₋₋ tokens array. The value of theselection mask determinesthe action to be performed, i.e. "vm₋₋ evn₋₋ select₋₋ off" means stopmonitoring of the monitor identified by the corresponding element of themonitor₋₋ tokens array, and "vm₋₋ evn₋₋ select₋₋ on" means startmonitoring of the monitor identified by the corresponding element of themonitor₋₋ tokens array.

EventQuery--An application program can call this function to obtaininformation about an existing event definition, including a list of allevent monitors defined in the current process which are sensitive tooccurrences of the event. The EventMonitorQuery function may be used toobtain further information about a particular event monitor.

    ______________________________________                                        EventQuery       retcode                                                                       rsncode                                                                       event.sub.-- name                                                             event.sub.-- name.sub.-- length                                               event.sub.-- flag                                                             event.sub.-- flag.sub.-- size                                                 event.sub.-- flag.sub.-- count                                                loose.sub.-- signal.sub.-- limit                                              signal.sub.-- timeout.sub.-- period                                           loose.sub.-- signal.sub.-- count                                              event.sub.-- selection.sub.-- mask                                            event.sub.-- enablement.sub.-- mask                                           monitor.sub.-- token                                                          monitor.sub.-- token.sub.-- size                                              monitor.sub.-- token.sub.-- count                            ______________________________________                                    

Parameters:

"EventQuery" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventQuery.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventQuery.

"Event₋₋ name" is a character variable which contains the name of theevent to be queried.

"Event₋₋ name₋₋ length" is a signed 4-byte binary variable containingthe length of event₋₋ name.

"Event₋₋ flag" is an array of signed 4-byte binary variables in which isreturned information about how the event is managed. Exactly oneoptionfrom each of the following sets is included.

The scope of the event name is indicated either by "vm₋₋ evn₋₋ process₋₋scope" which means the designated process, or "vm₋₋ evn₋₋ session₋₋scope" which-means the designated session.

The manner in which an event signal is propagated to multiple eventmonitors is indicated by "vm₋₋ evn₋₋ broadcast₋₋ signals" which meansbroadcast "vm₋₋ evn₋₋ fifo₋₋ signals" which means FIFO sequence, or"vm₋₋ evn₋₋ lifo₋₋ signals" which means LIFO sequence.

The treatment of the signaler is indicated by "vm₋₋ evn₋₋ async₋₋signals" which means that the signaling thread is allowed to continueexecuting (the default), "vm₋₋ evn₋₋ sync₋₋ thread₋₋ signals" whichmeans that the signaling thread is suspended to await the outcome ofevent processing, or "vm₋₋ evn₋₋ sync₋₋ process₋₋ signals" which meansthat all threads in the signaling process, with the exception of thosethreads running as the result of a monitor activated by this signal, aresuspended to await the outcome of event processing.,

"Event₋₋ flag₋₋ size" is a signed 4-byte binary variable containing thenumber of elements in the event₋₋ flag array.

"Event₋₋ flag₋₋ count" is a signed 4-byte binary variable in which isreturned the number of elements in the event₋₋ flag array which havebeen set by EventQuery.

"Loose₋₋ signal₋₋ limit" is a signed 4-byte binary variable in which isreturned the number of event signals which may be retained if noeligible event monitor exists to which to bind the signal or if aprocess is not monitoring for the event at the time the event issignaled. When the limit is exceeded, the oldest loose signal isdiscarded to make room for the newest arrival. A value of 0 indicatesthat no loose signals are retained. A value of negative one (-1 ) meansthat the loose signal set isallowed to grow without limit, subject tothe availability of virtual storage.

"Signal₋₋ timeout₋₋ period" is a signed 4-byte binary variable inwhichis returned the maximum length of time, specified in microseconds, thata signaling thread is allowed to remain suspended awaiting thecompletion of processing of the signal. A value of 0 indicates that thesignaling thread waits indefinitely for the completion of signalprocessing. If the option specifying that the signaling thread is tocontinue processing is included in the event₋₋ flag array, then thisparameter is meaningless.

"Loose₋₋ signal₋₋ count" is a signed 4-byte binary variable in which isreturned the number of loose signals currently being retained forthespecific event.

"Event₋₋ selection mask" is a signed 4-byte binary variable in which isreturned the state of the event selection mask; i.e. "vm₋₋ evn₋₋select₋₋ off" which means not monitoring for event₋₋ name, or "vm₋₋evn₋₋ select₋₋ on" which means monitoring for event₋₋ name.

"Event₋₋ enablement₋₋ mask" is a signed 4-byte binary variable inwhichis returned the state of the event enablement mask; i.e. "vm₋₋ evn₋₋disable" which means disabled for event name, or "vm₋₋ evn₋₋ enable"which means enabled for event₋₋ name. The event selection and enablementmasks are maintained on a process basis and are reported for the issuingprocess only.

"Monitor₋₋ token" is an array of signed 4-byte binary variables in whichis returned the list of tokens identifying the event monitors defined inthe current process which are sensitive to the specified event.Forevents defined as sequential, the tokens are output in the order inwhich they will be processed. For events defined as broadcast, thetokens are output in the order in which the monitors were created.

"Monitor₋₋ token₋₋ size" is a signed 4-byte binary variable containingthe number of elements in the monitor₋₋ token array which are availableto be filled in.

"Monitor₋₋ token₋₋ count" is a signed 4-byte binary variable in which isreturned the total number of event monitors defined in the currentprocess which are sensitive to the specified event. If monitor₋₋ token₋₋count is not greater than monitor₋₋ token₋₋ size, then the firstmonitor₋₋ token₋₋ count elements of the monitor₋₋ token array containthe tokens which identify that entire set of monitors and the remainderof the array is unchanged; otherwise, only the first monitor₋₋ token₋₋size monitor tokens are returned.

EventQueryAll--An application program can call this function to obtainthe names of all events and the tokens for all event monitors visible tothis process. The EventQuery and EventMonitorQuery functions may be usedto obtain further information about events and event monitors.

    ______________________________________                                        EventQueryAll     retcode,                                                                      rsncode,                                                                      number.sub.-- of.sub.-- events                                                event.sub.-- name.sub.-- address,                                             event.sub.-- name.sub.-- length                                               actual.sub.-- name.sub.-- length,                                             monitor.sub.-- token                                                          monitor.sub.-- token.sub.-- size                                              monitor.sub.-- token.sub.-- count                           ______________________________________                                    

Parameters:

"EventQueryAll" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventQueryAll.

"Rsncode" is a signed 4-byte binary variable to hold the reason codeform EventQueryAll.

"Number₋₋ of₋₋ events" is a signed 4-byte binary variable containing thenumber of elements in the following three arrays.

"Event₋₋ name₋₋ address" is an array of number₋₋ of₋₋ events 4-bytepointer variables each element of which contains the addressof acharacter variable in which is to be returned the name of a definedevent.

"Event₋₋ name₋₋ length" is an array of number₋₋ of₋₋ events signed4-byte binary variables, each element of which contains the length ofthe buffer of the corresponding element of the event₋₋ name₋₋ addressarray. If the name is longer than the buffer, it is truncated; ifshorter, the excess space at the end of the buffer is unchanged.

"Actual₋₋ name₋₋ length" is an array of number₋₋ of₋₋ events signed4-byte binary variables. This function uses this array to output thelengths of the event names pointed to by the corresponding element ofthe event₋₋ name₋₋ address array.

"Monitor₋₋ token" is an array of signed 4-byte binary variables in whichis returned the list of tokens identifying all the event monitorsdefined in the current process.

"Monitor₋₋ token₋₋ size" is a signed 4-byte binary variable containingthe number of elements in the monitor₋₋ token array that are availableto be filled in.

"Monitor₋₋ token₋₋ count" is a signed 4-byte binary variable in which isreturned the total number of event monitors defined in the currentprocess. If monitor₋₋ token₋₋ count is not greater than monitor₋₋token₋₋ size, then the first monitor₋₋ token₋₋ count elements of themonitor₋₋ token array contain the tokens that identify that entire setof monitors and the remainder of the array is unchanged. Otherwise, onlythe first monitor₋₋ token₋₋ size monitor tokens are returned.

    ______________________________________                                        EventRetrieve      retcode                                                                       rsncode                                                                       monitor.sub.-- token                                                          index                                                                         data.sub.-- buffer                                                            data.sub.-- buffer.sub.-- length                                              event.sub.-- data.sub.-- length                            ______________________________________                                    

Parameters:

"EventRetrieve" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventRetrieve.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventRetrieve.

"Monitor₋₋ token" is a signed 4-byte binary variable containing thetoken which identifies the monitor from whose current signal set theretrieval is to be performed. A value of 0 may be used to identify theactive event monitor which was most recently activated on the currentthread.

"Index" is a signed 4-byte binary variable identifying, as an index intothe event₋₋ name₋₋ address, event₋₋ name₋₋ length, event₋₋ key₋₋address, and event₋₋ key₋₋ length arraysspecified in the creation of theevent monitor, the event₋₋ name and event₋₋ key pair corresponding tothe signal from which the data is to be retrieved.

"Data buffer" is a character variable in which is returned the signaleddata for the event₋₋ name and event₋₋ key pair identified by index.

"Data₋₋ buffer₋₋ length" is a signed 4-byte binary variable containingthe defined length of data₋₋ buffer.

"Event₋₋ data₋₋ length" is a signed 4-byte binary variable in which isreturned the length of the signaled data for the event₋₋ name andevent₋₋ key pair identified by index. If event₋₋ data₋₋ length isgreater than data₋₋ buffer₋₋ length, the signaled data is truncated onthe right and a warning return code is generated.

    ______________________________________                                        EventSelect        retcode                                                                       rsncode                                                                       number.sub.-- of.sub.-- events                                                event.sub.-- name.sub.-- address                                              event.sub.-- name.sub.-- length                                               event.sub.-- selection.sub.-- mask                         ______________________________________                                    

Parameters:

"EventSelect" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventSelect.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventSelect.

"Number₋₋ of₋₋ events" is a signed 4-byte binary variable containing thenumber of events of interest.

"Event₋₋ name₋₋ address" is an array of number₋₋ of₋₋ events 4-bytepointer variables each element of which contains the addressof the nameof an event whose signals are to be selected on or off.

"Event₋₋ name₋₋ length" is an array of number₋₋ of₋₋ events signed4-byte binary variables each element of which contains the length of theevent₋₋ name pointed to by the corresponding element ofthe event₋₋name₋₋ address array.

"Event₋₋ selection₋₋ mask" is an array of number₋₋ of₋₋events signed4-byte binary variables each element of which contains the selectionmask of the event₋₋ name pointed to by the corresponding element of theevent₋₋ name₋₋ address array. The value of the selection mask determinesthe action to be performed, i.e. "vm₋₋ evn₋₋ select₋₋ off" which meansstop monitoring of the event₋₋ name pointed to by the correspondingelement of the event₋₋ name₋₋ address array, or "vm₋₋ evn₋₋ select₋₋ on"which means start monitoring of the event₋₋ name pointed to by thecorresponding element of the event₋₋ name₋₋ address array.

    ______________________________________                                        EventSignal       retcode                                                                       rsncode                                                                       event.sub.-- name                                                             event.sub.-- name.sub.-- length                                               event.sub.-- data                                                             event.sub.-- data.sub.-- length                                               event.sub.-- key.sub.-- offset                                                event.sub.-- key.sub.-- length                              ______________________________________                                    

Parameters:

"EventSignal" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventSignal.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventSignal.

"Event₋₋ name" is a character variable which contains the name of theevent whose occurrence is to be signaled.

"Event₋₋ name₋₋ length" is a signed 4-byte binary variable containingthe length of event₋₋ name.

"Event₋₋ data" is a character variable which contains data to be madeavailable to any interested event monitors.

"Event₋₋ data₋₋ length" is a signed 4-byte binary variable key givingthe length of event₋₋ data.

"Event₋₋ key₋₋ offset" is a signed 4-byte binary variable which containsthe offset in event₋₋ data of the first byte of a key that characterizesthe particular instance of the event to be signaled.

"Event₋₋ key₋₋ length" is a signed 4-byte binary variable which containsthe length of the key contained in event₋₋ data. The key maybe null(that is, its length may be 0) if no secondary characterization of theevent is necessary for this type of event or for this occurrence of theevent.

    ______________________________________                                        EventTest         retcode                                                                       rsncode                                                                       monitor.sub.-- token                                                          number.sub.-- of.sub.-- events                                                event.sub.-- flag                                           ______________________________________                                    

Parameters:

"EventTest" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventTest.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventTest.

"Monitor₋₋ token" is a signed 4-byte binary variable containing thetoken which identifies the monitor whose condition is to be tested. Avalue of 0 may be used to identify the active event monitor mostrecently activated on the current thread.

"Number₋₋ of₋₋ events" is a signed 4-byte binary variable containing thenumber of events whose occurrence is to be tested. In general, thisshould be the same as the number of event₋₋ name and event₋₋ keycombinations specified in the definition of the event monitor.

"Event₋₋ flag" is an array of number₋₋ of₋₋ events signed 4-byte binaryvariables in each element of which is returned an indicationof theoccurrence or non-occurrence of the event identified by the event₋₋ nameand event₋₋ key pair specified by the correspondingelements of theevent₋₋ name₋₋ address, event₋₋ name₋₋ length, event₋₋ key₋₋ address,and event₋₋ key₋₋ length arrays used in defining the event monitor, i.e.

    __________________________________________________________________________    0, 1, 2, . . .                                                                       indicates that the event has been                                             signaled, the number is the length                                            of data provided on the                                                       signal that may be obtained with                                              the EventRetrieve function.                                            -1     indicates that the event has not been                                         signaled,                                                              -2     indicates that the event definition has                                       been deleted, and                                                      -3     indicates no corresponding event.sub.-- name                                  and event.sub.-- key pair was defined                                         in the event monitor.                                                         Event Trap          retcode                                                                       rsncode                                                                       monitor.sub.-- token                                                          trap.sub.-- routine.sub.-- address                                            trap.sub.-- routine.sub.-- name                    __________________________________________________________________________

Parameters:

"EventTrap" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventTrap.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventTrap.

"Monitor₋₋ token" is a signed 4-byte binary variable containing thetoken that identifies the monitor whose condition is to be trapped. Avalue of 0 may be used to identify the active event monitor that wasmost recently activated on the current thread.

"Trap₋₋ routine₋₋ address" is a 4-byte binary variable containingtheaddress of the routine to be invoked when the condition defined by themonitor is satisfied. If an address was previously associated with theevent monitor, it is automatically replaced by the new trap₋₋ routine₋₋address. If the address is a non-zero value, the trap₋₋ routine₋₋ nameparameter is meaningless.

"Trap₋₋ routine₋₋ name" is a 8-byte character variable containingthename of the routine to be invoked when the condition defined by themonitor is satisfied. This parameter has meaning only if the trap₋₋routine₋₋ address parameter is zero. If a name was previously associatedwith the event monitor, it is automatically replaced by the newtrap₋₋routine₋₋ name. If the trap₋₋ routine₋₋ address parameter is zero andthe trap₋₋ routine₋₋ name is blank, the trap associated with thespecified event monitor is cancelled.

    ______________________________________                                        EventWait         retcode                                                                       rsncode                                                                       monitor.sub.-- token                                                          number.sub.-- of.sub.-- events                                                event.sub.-- flag                                           ______________________________________                                    

Parameters:

"EventWait" is the name of the function being invoked.

"Retcode" is a signed 4-byte binary variable to hold the return codefrom EventWait.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom EventWait.

"Monitor₋₋ token" is a signed 4-byte binary variable containing thetoken which identifies the monitor whose condition is to be awaited. Themonitor must not already be in the waiting state; there may be no morethan one wait outstanding to a monitor at a time. A value of 0 may beusedto identify the active event monitor which was most recentlyactivated on the current thread.

"Number₋₋ of₋₋ events" is a signed 4-byte binary variable containing thenumber of events whose occurrence is to be indicated when the EventWaitfunction completes. In general, this should be the same as the number ofevent₋₋ name and event₋₋ key combinations specified in the definition ofthe event monitor.

"Event₋₋ flag" is an array of number₋₋ of₋₋ events signed 4-byte binaryvariables in each element of which is returned an indicationof theoccurrence or non-occurrence of the event identified by the event₋₋ nameand event₋₋ key pair specified by the correspondingelements of theevent₋₋ name₋₋ address, event₋₋ name₋₋ length, event₋₋ key₋₋ address,and event₋₋ key₋₋ length arrays used in defining the event monitor, i.e.

    ______________________________________                                        0, 1, 2, . . .                                                                           indicates that the event has been signaled,                                   the number is the length of data provided on                                  the signal that may be obtained with the                                      EventRetrieve function.                                            -1         indicates that the event has not been                                         signaled,                                                          -2         indicates that the event definition has been                                  deleted, and                                                       -3         indicates no corresponding event.sub.-- name and                              event.sub.-- key pair was defined in the event                                monitor.                                                                      TRACE TABLES                                                       ______________________________________                                    

The event management services described above can be used to establishand process trace tables in the following manner when the events aretrace events. As noted above, each event definition includes a loosesignal limit which specifies a maximum number of event signals which canbe stored, tied to the event definition in loose signal set 41 whenthere is no interested event monitor (which is selected-on). When theloose signal limit is reached, each subsequent event signal is stored atthe expense ofthe oldest event signal; the newer event signals generallyprovide more important trace information. Therefore, the loose signalset can be used as a trace table, or a "pool" of event signals for asubsequently defined event monitor by delaying definition of aninterested event monitor. When a process is interested in processing thetrace event signals, the processdefines an event monitor which isinterested in the event and calls the EventWait function, EventTrapfunction or EventTest function. As a result of the creation of the eventmonitor, the loose signals for the event(s) of interest to the eventmonitor will be transferred to the bound signal set of the event monitoras described above with reference to FIG. 17. If there are enough ofthese signals to satisfy the event monitor, then the event monitor willestablish the current signal set in response to the call to theEventWait function, EventTrap function, or EventTest function,and theevent handler within the associated process can access the event signalswithin the current signal set.

Thus, the loose signal set of one or more event definitions can beaccessedby interested event handlers according to their specificrequirements by subsequently defining appropriate event monitors. Also,each event handlercan access the trace table in real time, i.e., uponrequest, and can process the trace data directly from the current signalset (without having to access any external storage device such as aDirect Access Storage Device DASD).

The transfer from the loose signal set to the bound signal set can becontrolled in different ways using the foregoing functions. If an eventmonitor interested in all trace signals is created without firstselectingthe event off, all the loose signals within the loose signalset for that event will be transferred to the event monitor and then theloose signal set will be entirely depleted. As a result, if a secondinterested event monitor is subsequently defined, these loose signalswill not be availableto the second interested event monitor. However, iftwo or more event monitors need a copy of the loose signal set, then thefollowing procedurecan be utilized to provide the loose signals to allthe event monitors. Theevent of interest is first selected-off by a callto the EventSelect function (step 254 of FIG. 14), which will then markthe event definition as "selected-off". Next, the event monitors aredefined, and afterwards, the event is selected-on by another call to theEventSelect function (step266 of FIG. 14). In response, the EventSelectfunction will mark the event definition as selected-on (step 268) andidentify all event monitors whichare interested in the event by readingthe event monitor definitions (step 270). Next, the EventSelect functionwill transfer copies of all loose signals to all such interested eventmonitors if the broadcast mode has been designated in the eventdefinition (and erase the loose signal set), or transfer all the loosesignals to the first event monitor in the sequence if the propagationmode has been designated in the event definition (and erase the loosesignal set) (step 272).

Also as noted above, each event monitor definition includes a boundsignal limit and a satisfaction level for each event of interest to theevent monitor. The bound signal limit for each event indicates themaximum number of event signals for the event that can be stored boundto the event monitor. When the next event signal for this event type isreceived,it is stored at the expense of the oldest event signal for thesame type ofevent. The bound signal limits for different events ofinterest to the sameevent monitor can vary. The satisfaction level foreach event indicates thenumber of occurrences of the event required topermit the event monitor to provide the associated event handler withthe event signals from the current signal set. The satisfaction levelsfor different events of interest to the same event monitor can vary.Only when the satisfaction levels are met for all events is the eventhandler permitted to access thecurrent signal set. Any number of eventmonitors can be defined, and the definitions can reference the same,different or partially overlapping sets of event types. One event or setof events can be of interest to multiple event monitors. Eachapplication program can specify its own parameters for its event monitoror monitors, i.e. event types of interest, bound limits, andsatisfaction levels. Also, each application program can control its owntrace table with calls to the EventDelete function 69, EventEnablefunction 44, EventModify function 71, EventMonitorDelete function 68,EventMonitorEnable 64, and EventMonitorSelect function 66. Such control,as well as the creation of the event monitor, can be made at any time,i.e. dynamically.

Therefore, as an alternative to utilizing the loose signal set as atrace table or a pool for a subsequently defined event monitor, theevent monitors can be defined before occurrences of the event(s) ofinterest, and used directly to provide the trace table. The bound limitsestablish the "wrap sizes" and the satisfaction levels establish thenumber of signals of each type to be made available to the event handlerupon request. In this configuration, if the event handler calls theEventTrap or EventWait function before the event monitor is satisfied,then the event handler can access the trace table (current signal set)in real time, i.e. as soon as the event monitor satisfied. Also, whenthe current signal set is established and the event handler accesses thecurrent signal set, the current signal set is erased to make room fornew event signals in the bound signal set. While this alternatearrangement provide some advantages over the use of the loose signal setas a trace table or pool, the alternate arrangement may require asomewhat higher operating system overhead when multiple event monitorsare interested in the same event because all event signals in thealternate arrangement are transferred to the bound signal set of allevent monitors, even those in excess of the loose signal limit. Incontrast, in the other arrangement which utilizes the loose signal setas a trace table or pool, the maximum number of event signals thatrequire the overhead of subsequent transfer to an event monitor is theloose signal limit.

To facilitate and ensure proper establishment, management, and use ofthe trace tables, the following additional trace management servicesincludingan application program interface are provided. The tracemanagement services are controlled by ITRACE and ETRACE keyboardcommands, or a TRACECONTROL call. The TRACECONTROL call defines whichtrace events of a predetermined set should be signalled and theattributes of the signalled trace events, as well as provide someadditional trace processing options.The TRACECONTROL call is made to aconversational monitor system (CMS) portion of operating system 11. Manyof the standard functions of the conversational monitor system portionof operating system 11 are describedin a publication entitled VM/ESA CMSApplication Development Reference, published June 1990 by IBM Corp. ofArmonk, N.Y. IBM order number SC24-5451-00. The format for theTRACECONTROL call is as follows:

    ______________________________________                                        TRACECONTROL       Rtncode                                                                       Rsncode                                                                       Traceflg                                                                      Wrapsize                                                                      Function                                                                      N                                                                             Tracetype(N)                                                                  Tracetype.sub.-- Setting(N)                                ______________________________________                                    

Parameters:

"Rtncode" is a signed 4-byte binary variable to hold the return codefrom TRACECONTROL.

"Rsncode" is a signed 4-byte binary variable to hold the reason codefrom TRACECONTROL.

"Traceflg" specifies to what degree the signaller of a trace event is tobesynchronized. It is a signed four byte binary integer with validvalues as follows:

    ______________________________________                                        0     (ASYNC)    signalling thread continues processing                                        independently of event processing.                           1     (TSYNC)    signalling thread is suspended to await                                       outcome of event processing.                                 2     (PSYNC)    signalling process is suspended to await                                      outcome of event processing.                                 3     (DSYNC)    signalling process and all its                                                descendants are suspended to await the                                        outcome of event processing.                                 -1    (UNCH)     synchronization is unchanged.                                ______________________________________                                    

"Wrapsize" specifies how many trace events are retained if no eligibletrace event monitor exists at the time the event is signalled. Thiscorresponds to the loose signal limit. When the wrapsize is exceeded,the oldest trace event is discarded to make room for the newest arrival.This is a four byte signed binary integer. A value of 0 indicates thatno traceevents are to be retained. A value of -1 indicates that traceevents will continue to be retained until virtual storage is exhausted.A value of -2 indicates the wrapsize is to remain unchanged. Any othernegative value isinvalid.

"Function" specifies the use of the arrays to follow. It is a four bytesigned binary integer with valid values as follows:

    ______________________________________                                        0    (QUERY ITRACE) The ITRACE tracetypes are                                                     queried and their setting is returned                                         in the tracetype.sub.-- settings array.                   1    (QUERY ETRACE) The ETRACE tracetypes are                                                     queried and their setting is returned                                         in the tracetype.sub.-- settings array.                   2    (ITRACE)       The tracetypes and                                                            tracetype.sub.-- settings are used as a                                       callable interface to the ITRACE                                              command.                                                  3    (ETRACE)       The tracetypes and                                                            tracetype.sub.-- settings are used as a                                       callable interface to the ETRACE                                              command.                                                  -1   (UNCH)         Indicates that the follows arrays                                             are to be ignored.                                        ______________________________________                                    

"N" Specifies the number of trace types to be set. It is a four bytesignedbinary integer.

"Tracetype" Specifies the trace types to be set. It is an array of4-byte signed binary integers with the following valid values:

    ______________________________________                                        0      (ALL)       All trace types                                            1      (COMM)      Communication events                                       2      (DISP)      Dispatch events                                            3      (STOR)      Storage Management events                                  4      (IO)        I/O events                                                 5      (PRGMAN)    Program Management events                                  6      (PRCMAN)    Process Management events                                  7      (MISC)      Timer, external interrupt and                                                 machine check events                                       8      (DTMAN)     Data Management events                                     9      (GROUP)     Previous settings are for all                                                 machines in the virtual machine                                               group.                                                     ______________________________________                                    

"Tracetype₋₋ Setting" Specifies the settings corresponding to the tracetype array. It is an array of 4-byte signed binary integers withthefollowing valid values:

    ______________________________________                                        0       (OFF)    Corresponding trace type is set OFF.                         1       (ON)     Corresponding trace type is set ON.                          ______________________________________                                    

The TRACECONTROL call always results in an event definition of sessionscope and broadcast signals. If the signalling thread does not continueindependently of the event processing, the suspended thread will waitindefinitely, i.e. there is no timeout period. The tracetype andtracetype₋₋ setting arrays are processed in array order. For example,ifvalues corresponding to ALL and OFF are the first elements in therespective arrays, all trace categories are set off before processingsubsequent elements in the arrays. As a result, in general, an arrayelement may be nullified by a subsequent array element. CMS will invokethe TRACECONTROL routine with the following parameter settings as partof its initialization--Function =ITRACE, Traceflg=ASYNC,Wrapsize=determined from DMSNGP, N=1, Tracetype=ALL, and Tracetype₋₋Setting=ON. These settings are set before the system profile is executedand thus may be overridden by the system profile.

The ITRACE keyboard command is similar in effect to the TRACECONTROL APIcall, and specifies which of the predefined, trace events are selectedforsignalling by CMS to the event signal manager, and the "wrap size" orthe loose signal limit. The format is as follows:

    ______________________________________                                        ITRACE                                                                        ALL                   ON/OFF                                                  COMMUNICATION         ON/OFF                                                  DISPATCH              ON/OFF                                                  STORAGE               ON/OFF                                                  I/O                   ON/OFF                                                  PROGMAN               ON/OFF                                                  PROCMAN               ON/OFF                                                  DATAMAN               ON/OFF                                                  MISC                  ON/OFF                                                  GROUP                 ON/OFF                                                  END                                                                           WRAPSIZE              XXXXXXXX                                                ______________________________________                                    

"All" specifies whether or not all trace entries will be signalled.Permissible values are:

    ______________________________________                                        ON            trace entries are signalled.                                    OFF           trace entries are not signalled.                                ______________________________________                                    

"Communication" specifies whether or not communication trace entrieswill be signalled. Possible examples of this type of trace entry areIUCV and APPC transactions and queue operations. Permissible values are:

    ______________________________________                                        ON            trace entries are signalled.                                    OFF           trace entries are not signalled.                                ______________________________________                                    

"Dispatch" specifies whether or not dispatch trace entries will besignalled. Possible examples of this type of trace entry are ThreadDispatch and Thread Priority Modification. Permissible values are:

    ______________________________________                                        ON            trace entries are signalled.                                    OFF           trace entries are not signalled.                                ______________________________________                                    

"Storage" specifies whether or not storage trace entries will besignalled.Possible examples of this type of trace entry are Free StorageObtain and Free Storage Return. Permissible values are:

    ______________________________________                                        ON            trace entries are signalled.                                    OFF           trace entries are not signalled.                                ______________________________________                                    

"I/O" specifies whether or not I/O trace entries will be signalled.Possible examples of this type of trace entry are requests for I/O andI/Ointerrupt occurrences. Permissible values are:

    ______________________________________                                        ON            trace entries are signalled.                                    OFF           trace entries are not signalled.                                ______________________________________                                    

"Progman" specifies whether or not program management trace entries willbesignalled. Possible examples of this type of trace entry are CommandLoad and Program Load. Permissible values are:

    ______________________________________                                        ON            trace entries are signalled.                                    OFF           trace entries are not signalled.                                ______________________________________                                    

"Procman" specifies whether or not process management trace entries willbesignalled. Possible examples of this type of trace entry are ProcessCreateand Thread Create. Permissible values are:

    ______________________________________                                        ON            trace entries are signalled.                                    OFF           trace entries are not signalled.                                ______________________________________                                    

"Dataman" specifies whether or not data management trace entries will besignalled. Possible examples of this type of trace entry are File SystemRead and File System Write. Permissible values are:

    ______________________________________                                        ON            trace entries are signalled.                                    OFF           trace entries are not signalled.                                ______________________________________                                    

"Misc" specifies whether or not trace entries not lending themselves tocategorization will be signalled. Possible examples of this type oftrace entry are machine checks, external interrupts and timerinterrupts. Permissible values are:

    ______________________________________                                        ON            trace entries are signalled.                                    OFF           trace entries are not signalled.                                ______________________________________                                    

"Group" specifies whether or not trace entries to be signalled aresignalled in all machines in the issuer's virtual machine group. Thisoperand applies only to those trace entries currently being signalledwhenthe GROUP operand is processed. That is, operands to the right ofthe GROUPoperand are not affected by the GROUP operand. This operand maynot be specified by virtual machines which are not part of a group.Permissible values are:

    ______________________________________                                        ON          trace entries are signalled in all                                            machines in the virtual machine group.                            OFF         trace entries are not signalled in any                                        other machine in the virtual machine                                          group.                                                            ______________________________________                                    

"End" specifies that no trace entries are to be signalled.

"Wrapsize xxx" specifies how many trace entries are retained in thetrace table if no eligible trace event monitor exists at the time thetrace entry is signalled. When the wrapsize is exceeded,.the oldesttrace entry is discarded to make room for the newest arrival. A value of0 indicates that no trace entries are to be retained.

The ETRACE command specifies which of the Selected trace events shouldbe sent to a predetermined event handler within a control program of theoperating system 11 for the purpose of recording the event signals in aspool file. The control program provides many standard functions asdescribed in a publication entitled VM/ESA Diagnostics Guide for 370,published by IBM Corp of Armonk N.Y. in June 1990, IBM order numberLY24-5242-00. The format for the ETRACE command is as follows:

ETRACE EVENTNAME ON OR OFF, EVENTNAME ON OR OFF ETC.

The steps involved in utilizing the trace management services are asfollows:

First, an application program issues the TRACECONTROL call or a userentersthe ITRACE command through the keyboard to define which traceevents will be built and signalled, as well as the wrap size. Next, thetrace events occur at appropriate points in the processing of CMS, andCMS, which serves as a signaller, signals the trace events including theevent data. The format for the trace entries is as follows:

1. HEADER LENGTH--Length of the trace header information.

2. USERID--Userid of the virtual machine issuing the trace signal.

3. PROCESSID--Unique process identifier of the process on whose behalfthistrace entry is being signalled.

4. THREADID--Unique thread identifier of the thread on whose behalf thistrace entry is being signalled.

5. TRACEID--The specific type of trace entry.

6. TIMESTAMP--Time at which the trace entry is being signalled (in timerunits).

7. FORMAT ROUTINE--Identifier of routine that is needed to format thistrace entry.

8. VARIABLE HEADER DATA--Other data which may be included in the header.

9. DATA LENGTH--Length of actual trace data.

10. VARIABLE DATA--Actual trace data.

As long as no event monitors are interested in the trace events, themaximum number of trace event signals which are stored is equal to thewrap size, and these trace events are stored in the loose signal set.Next, a user application program calls the EventMonitorCreate functionto establish an event monitor which is interested in the event. TheEventMonitorCreate call can include specification of a limiting key tolimit the interest of the event monitor. In this scenario, only thefirst event monitor which is established having interest in the eventwill receive the content of the loose signal set. Alternately, as notedabove, the event can be selected off before two or more event monitorsare created to provide copies of the loose signal set to the two or moreeventmonitors. Next, the user application program calls the EventWait orEventTrap function to obtain the current signal set when the eventmonitoris satisfied. The user application program is notified uponsatisfaction ofthe event monitor and can call the EventRetrieve functionto read the contents of the current signal set and then process theevent data.

It should be understood that even though the foregoing trace managementservices and application program interface refer to a virtual machineenvironment, they are useful in other environments.

FIGS. 18 and 19 are flowcharts illustrating an example of usage of thetrace management services and application program interface to trace(for trouble shooting purposes) which program threads in a multitaskingoperating system have been executed (for trouble shooting purposes) andthe time of execution for each thread. FIG. 18 illustrates the actualtrace management services and API which are involved in this function.In step 500, the operating system creates an event named "Trace" by acall tothe EventCreate function 40. Next, the user application programissues a TRACECONTROL call and specifies a Dispatch type of event-as aparameter inthe call (step 506). The operating system reads the Dispatchparameter fromthe call (step 508), and then notifies the dispatcher tosignal the Dispatch event (step 510). The dispatcher is the functionthat selects program threads for execution by CPU 19.

FIG. 19 is the flowchart for the dispatcher referenced in FIG. 18. Instep 530, the dispatcher removes an old thread from the CPU and startsexecution of a new thread. To provide event data to accompany the traceevent signal, the dispatcher reads the current time (with a clock notshown) (step 532), and stores this current time as being the time thatthenew thread started and the old thread halted execution (step 534).The dispatcher then computes the old thread's CPU execution time as thedifference between the current time and the start time for the oldthread which was previously stored (step 536). Next, the dispatchercalls the EventSignal function and provides the following event data:old thread ID,old thread CPU usage time, and new thread ID (step 540).

We claim:
 1. A computer program product for operating a computer, saidcomputer program product comprising:a computer readable medium; firstprogram instruction means for instructing a computer processor to form asequence in which a plurality of event handling programs or parts of thesame program can receive notification of an event; second programinstruction means for instructing a computer processor to notify a firstone of the programs or parts in the sequence of the occurrence of theevent; third program instruction means for instructing a computerprocessor to receive an indication from said first program or partwhether or not the event notification should be propagated to the nextprogram or part in the sequence; fourth program instruction means forinstructing a computer processor to propagate the event notification tosaid next program or part in the sequence if the indication is topropagate the event notification; and fifth program instruction meansfor instructing a computer processor to block propagation of the eventnotification to said next program or part in the sequence if theindication is not to propagate the event notification; and wherein eachof said program instruction means is recorded on said medium inexecutable form and is loadable into a computer memory for execution bythe associated processor to form part of an operating system.
 2. Acomputer program product as set forth in claim 1 further comprisingsixth program instruction means for instructing a computer processor toreceive, from one or more programs, input to define said sequence, andwhereinsaid first program instruction means instructs said computerprocessor to form said sequence based on said input; and said sixthprogram instruction means is recorded on said medium in executable formand is loadable into a computer memory for execution by the associatedprocessor to form part of said operating system.
 3. A computer productas set forth in claim 1 further comprising:sixth program instructionmeans for instructing a computer processor to receive parametersdefining said and other types of events, one of said parametersspecifying whether notification of the respective type of event can bepropagated sequentially to the next program or part in the sequencesubject to an indication by each of the programs or parts in thesequence which receive the event notification to propagate the eventnotification, or should be broadcast to every program or part of thesame program which are interested in the event with or without approvalby other of said programs or parts; and wherein said sixth programinstruction means is recorded on said medium in executable form and isloadable into a computer memory for execution by the associatedprocessor to form part of said operating system.
 4. A computer programproduct as set forth claim 3 further comprising:seventh programinstruction means for instructing a computer processor to broadcastnotification of an event type which is defined with the broadcastparameter to every one of said programs or parts in response to a signalof said event type; and wherein said seventh program instruction meansis recorded on said medium in executable form and is loadable into acomputer memory for execution by the associated processor to form partof said operating system.
 5. A computer program product as set forth inclaim 1 further comprising:sixth program instruction means forinstructing a computer processor to create a plurality of event monitorswhich sequentially receive notification of said event on behalf ofrespective ones of said programs or parts and pass said notification tothe respective program or part upon request by the respective program orpart; and wherein said sixth program instruction means is recorded onsaid medium in executable form and is loadable into a computer memoryfor execution by the associated processor to form part of said operatingsystem.
 6. A computer program product as set forth in claim 1 furthercomprising:sixth program instruction means for instructing a computerprocessor to receive an indication that the last program or program partin the sequence that receives the event notification has completedhandling of the event notification; and seventh program instructionmeans, responsive to said indication, for instructing a computerprocessor to indicate to a signaller of the event that the handling ofthe event has been completed; and wherein said sixth and seventh programinstruction means are recorded on said medium in executable form and areloadable into a computer memory for execution by the associatedprocessors to form part of said operating system.
 7. A computer programproduct as set forth in claim 1 wherein said first program instructionmeans instructs the computer processor to form a sequence of only saidprograms or program parts which are interested in said event.
 8. Acomputer program product as set forth in claim 7 wherein:said secondprogram instruction means instructs the computer processor to notifysaid first program or part in the sequence of the occurrence of twodifferent types of events, said first program or part being interestedin both types of events; said third program instruction means instructsthe computer processor to receive an indication from said first programor program part whether or not the notification of said second type ofevent can be propagated to the second program or program part in thesequence; said fourth program instruction means instructs the computerprocessor to propagate the notification of said second type of event tosaid second program or program part in the sequence only if said firstprogram or program part in the sequence indicates that the notificationfor said second type of event can be propagated and said second programor part is interested in the second type of event; and said fifthprogram instruction means instructs the computer processor to blockpropagation of the notification of said second type of event to saidsecond program or program part in the sequence if the indication is notto propagate notification of said second type of event even if saidsecond program or part is interested in said second type of event,whereby said first program or program part in the sequence can indicatewhether to propagate notifications of both, one or none of the types ofevents to said second program or program part in the sequence.
 9. Acomputer program product as set forth in claim 1 wherein said computerreadable medium comprises a magnetic medium.
 10. A computer programproduct as set forth in claim 1 wherein said computer readable mediumcomprises a semiconductor memory.